@unbrained/pm-cli 2026.8.7 → 2026.8.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (226) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +35 -0
  3. package/dist/cli/main.js +4 -3
  4. package/dist/cli/register-annotations.d.ts +11 -0
  5. package/dist/cli/register-annotations.js +195 -0
  6. package/dist/cli/register-history-author.js +7 -30
  7. package/dist/cli/register-mutation.js +25 -206
  8. package/dist/cli/runtime-compatibility-boundary.d.ts +17 -0
  9. package/dist/cli/runtime-compatibility-boundary.js +43 -0
  10. package/dist/cli-bundle/bundle-manifest.json +155 -691
  11. package/dist/cli-bundle/chunks/chunk-2ZMXX3Q6.js +2068 -0
  12. package/dist/cli-bundle/chunks/chunk-ALDHXLPS.js +3 -0
  13. package/dist/cli-bundle/chunks/chunk-CBLA33YK.js +8 -0
  14. package/dist/cli-bundle/chunks/chunk-GKA54IJM.js +5 -0
  15. package/dist/cli-bundle/chunks/chunk-KRY7SRUO.js +2 -0
  16. package/dist/cli-bundle/chunks/chunk-MNJ4NNSY.js +26 -0
  17. package/dist/cli-bundle/chunks/chunk-NUXRRNAB.js +77 -0
  18. package/dist/cli-bundle/chunks/chunk-OJPCFDDY.js +13 -0
  19. package/dist/cli-bundle/chunks/chunk-PFSD3DAN.js +194 -0
  20. package/dist/cli-bundle/chunks/chunk-QWRRFYK3.js +2 -0
  21. package/dist/cli-bundle/chunks/chunk-SQ7QZFQ6.js +2 -0
  22. package/dist/cli-bundle/chunks/{register-list-query-FJZCJ67O.js → register-list-query-WFZAMJHZ.js} +8 -8
  23. package/dist/cli-bundle/chunks/register-mutation-SOKKOTHQ.js +20 -0
  24. package/dist/cli-bundle/chunks/register-operations-5XQETS6E.js +2 -0
  25. package/dist/cli-bundle/chunks/register-setup-2HL5ZHMK.js +2 -0
  26. package/dist/cli-bundle/focused-chunks/chunk-54EU2UVO.js +2 -0
  27. package/dist/cli-bundle/focused-chunks/{chunk-VZFU2R4M.js → chunk-5FLBTZJQ.js} +2 -2
  28. package/dist/cli-bundle/focused-chunks/chunk-5GJ57YKN.js +2 -0
  29. package/dist/cli-bundle/focused-chunks/{chunk-HNL6IFGS.js → chunk-ANTMGYLI.js} +2 -2
  30. package/dist/cli-bundle/focused-chunks/chunk-CMDS3KYT.js +14 -0
  31. package/dist/cli-bundle/focused-chunks/{chunk-NBJKQP4S.js → chunk-DMKOMTTY.js} +2 -2
  32. package/dist/cli-bundle/focused-chunks/{chunk-CIXVQPB7.js → chunk-F5B3HBEZ.js} +2 -2
  33. package/dist/cli-bundle/focused-chunks/{chunk-R2LEMEV5.js → chunk-FI6DWU2M.js} +2 -2
  34. package/dist/cli-bundle/focused-chunks/{chunk-3K4XV2BF.js → chunk-FNOKJG6N.js} +2 -2
  35. package/dist/cli-bundle/focused-chunks/{chunk-RW5IYD4J.js → chunk-FPDYXZBK.js} +2 -2
  36. package/dist/cli-bundle/focused-chunks/{chunk-QHRTT7WT.js → chunk-GWI6YIKJ.js} +2 -2
  37. package/dist/cli-bundle/focused-chunks/{chunk-MHMTKV5V.js → chunk-HCUC62AB.js} +2 -2
  38. package/dist/cli-bundle/focused-chunks/{chunk-MOTJFQ3F.js → chunk-HGNKPSCB.js} +12 -12
  39. package/dist/cli-bundle/focused-chunks/{chunk-4VJQTS3P.js → chunk-IAS7PMLG.js} +2 -2
  40. package/dist/cli-bundle/focused-chunks/{chunk-TIKDBG4D.js → chunk-PL2EYDJK.js} +27 -27
  41. package/dist/cli-bundle/focused-chunks/chunk-SM2PJGP3.js +2 -0
  42. package/dist/cli-bundle/focused-chunks/{chunk-RPNYG5MO.js → chunk-TCSAPH33.js} +2 -2
  43. package/dist/cli-bundle/focused-chunks/chunk-U646T7Z6.js +18 -0
  44. package/dist/cli-bundle/focused-chunks/chunk-YKPE4PPY.js +2 -0
  45. package/dist/cli-bundle/focused-chunks/{chunk-YZEZAPJK.js → chunk-YSAHYUXX.js} +2 -2
  46. package/dist/cli-bundle/focused-chunks/{chunk-73JUDYXT.js → chunk-ZOLDTUU7.js} +2 -2
  47. package/dist/cli-bundle/main.js +13 -13
  48. package/dist/cli-bundle/sdk-authoring.js +1 -1
  49. package/dist/cli-bundle/sdk-contracts.js +1 -1
  50. package/dist/cli-bundle/sdk-core.js +38 -38
  51. package/dist/cli-bundle/sdk-governance.js +1 -1
  52. package/dist/cli-bundle/sdk-graph.js +1 -1
  53. package/dist/cli-bundle/sdk-merge.js +1 -1
  54. package/dist/cli-bundle/sdk-query.js +1 -1
  55. package/dist/cli-bundle/sdk-runtime.js +1 -1
  56. package/dist/cli-bundle/sdk-testing.js +1 -1
  57. package/dist/cli-bundle/sdk.js +2 -1
  58. package/dist/cli.js +14 -4
  59. package/dist/core/output/output.js +9 -2
  60. package/dist/core/sentry/helpers.d.ts +10 -0
  61. package/dist/core/sentry/helpers.js +59 -4
  62. package/dist/core/shared/constants.d.ts +2 -0
  63. package/dist/core/shared/constants.js +4 -2
  64. package/dist/sdk/annotations.d.ts +40 -0
  65. package/dist/sdk/annotations.js +61 -9
  66. package/dist/sdk/author-attribution.d.ts +12 -0
  67. package/dist/sdk/author-attribution.js +73 -11
  68. package/dist/sdk/cli-contracts/command-exit-contracts.d.ts +118 -0
  69. package/dist/sdk/cli-contracts/command-exit-contracts.js +152 -0
  70. package/dist/sdk/cli-contracts/completeness.js +5 -3
  71. package/dist/sdk/cli-contracts/flag-contracts.js +5 -2
  72. package/dist/sdk/cli-contracts/runtime-contracts.d.ts +11 -0
  73. package/dist/sdk/cli-contracts/runtime-contracts.js +29 -2
  74. package/dist/sdk/cli-contracts/tool-parameter-tables.js +15 -2
  75. package/dist/sdk/cli-contracts/tool-schema.d.ts +1 -1
  76. package/dist/sdk/cli-contracts/tool-schema.js +6 -3
  77. package/dist/sdk/comments.d.ts +7 -0
  78. package/dist/sdk/comments.js +2 -2
  79. package/dist/sdk/completion.js +9 -5
  80. package/dist/sdk/contracts.d.ts +1 -0
  81. package/dist/sdk/contracts.js +3 -2
  82. package/dist/sdk/environment/host-environment-errors.d.ts +27 -0
  83. package/dist/sdk/environment/host-environment-errors.js +124 -0
  84. package/dist/sdk/environment/project-runtime-compatibility.d.ts +65 -0
  85. package/dist/sdk/environment/project-runtime-compatibility.js +385 -0
  86. package/dist/sdk/environment/source-context.d.ts +23 -0
  87. package/dist/sdk/environment/source-context.js +29 -0
  88. package/dist/sdk/error-code-catalog.d.ts +6 -0
  89. package/dist/sdk/error-code-catalog.js +62 -8
  90. package/dist/sdk/generated-error-code-catalog.js +629 -3
  91. package/dist/sdk/governance/health.d.ts +11 -3
  92. package/dist/sdk/governance/health.js +5 -5
  93. package/dist/sdk/index.d.ts +7 -3
  94. package/dist/sdk/index.js +9 -5
  95. package/dist/sdk/learnings.d.ts +15 -0
  96. package/dist/sdk/learnings.js +2 -2
  97. package/dist/sdk/lifecycle/close-many.d.ts +6 -1
  98. package/dist/sdk/lifecycle/close-many.js +43 -5
  99. package/dist/sdk/lifecycle/update-many.d.ts +2 -1
  100. package/dist/sdk/lifecycle/update-many.js +29 -5
  101. package/dist/sdk/merge/index.d.ts +1 -1
  102. package/dist/sdk/merge/index.js +3 -3
  103. package/dist/sdk/merge/install.d.ts +21 -0
  104. package/dist/sdk/merge/install.js +50 -20
  105. package/dist/sdk/notes.d.ts +7 -0
  106. package/dist/sdk/notes.js +2 -2
  107. package/dist/sdk/read-output-contracts.js +83 -4
  108. package/dist/sdk/runtime.d.ts +1 -1
  109. package/dist/sdk/runtime.js +9 -25
  110. package/dist/sdk/test/execution.js +4 -2
  111. package/dist/sdk/test/parsers.js +5 -2
  112. package/dist/sdk/workspace-snapshot.d.ts +9 -0
  113. package/dist/sdk/workspace-snapshot.js +48 -16
  114. package/docs/AGENT_RUNTIME_PRIMITIVES.md +11 -4
  115. package/docs/README.md +1 -0
  116. package/docs/RELEASING.md +27 -2
  117. package/docs/SCRIPTING.md +27 -1
  118. package/docs/SDK_CONTEXT_INTEGRITY.md +66 -0
  119. package/docs/SDK_RUNTIME_BOUNDARIES.md +58 -0
  120. package/docs/SELF_DESCRIBING_CONTEXT_CONTRACTS.md +13 -0
  121. package/docs/TESTING.md +17 -0
  122. package/marketplace.json +2 -2
  123. package/package.json +5 -3
  124. package/packages/pm-beads/package.json +1 -1
  125. package/packages/pm-calendar/package.json +1 -1
  126. package/packages/pm-command-kit/package.json +1 -1
  127. package/packages/pm-digital-twin/package.json +1 -1
  128. package/packages/pm-governance-audit/package.json +1 -1
  129. package/packages/pm-guide-shell/package.json +1 -1
  130. package/packages/pm-kanban/package.json +1 -1
  131. package/packages/pm-lifecycle-hooks/package.json +1 -1
  132. package/packages/pm-linked-test-adapters/package.json +1 -1
  133. package/packages/pm-search-advanced/package.json +1 -1
  134. package/packages/pm-templates/package.json +1 -1
  135. package/packages/pm-todos/package.json +1 -1
  136. package/packages/pm-vcs/package.json +1 -1
  137. package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
  138. package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
  139. package/sdk/public-surface.json +529 -34
  140. package/dist/cli-bundle/chunks/append-7BXBFDGD.js +0 -2
  141. package/dist/cli-bundle/chunks/chunk-2AXF3VSK.js +0 -2
  142. package/dist/cli-bundle/chunks/chunk-2XS43CCV.js +0 -2
  143. package/dist/cli-bundle/chunks/chunk-3A6KWB72.js +0 -8
  144. package/dist/cli-bundle/chunks/chunk-3ISTDB42.js +0 -8
  145. package/dist/cli-bundle/chunks/chunk-4MTI7XOV.js +0 -5
  146. package/dist/cli-bundle/chunks/chunk-6BX5UDCN.js +0 -3
  147. package/dist/cli-bundle/chunks/chunk-6QPO7KLR.js +0 -2
  148. package/dist/cli-bundle/chunks/chunk-7MXHZHSQ.js +0 -5
  149. package/dist/cli-bundle/chunks/chunk-7ZPMJW4U.js +0 -2
  150. package/dist/cli-bundle/chunks/chunk-A6KGKEWT.js +0 -2
  151. package/dist/cli-bundle/chunks/chunk-AGYNSNCI.js +0 -2
  152. package/dist/cli-bundle/chunks/chunk-B4H7FEFH.js +0 -5
  153. package/dist/cli-bundle/chunks/chunk-B4KLBBMN.js +0 -2
  154. package/dist/cli-bundle/chunks/chunk-BXCSXK4J.js +0 -2
  155. package/dist/cli-bundle/chunks/chunk-CALJHNBL.js +0 -23
  156. package/dist/cli-bundle/chunks/chunk-CFIGP5LY.js +0 -2
  157. package/dist/cli-bundle/chunks/chunk-CHOQ2VAW.js +0 -2
  158. package/dist/cli-bundle/chunks/chunk-CS6MRHG7.js +0 -2
  159. package/dist/cli-bundle/chunks/chunk-CUGNQQKH.js +0 -2
  160. package/dist/cli-bundle/chunks/chunk-D4FPS43D.js +0 -164
  161. package/dist/cli-bundle/chunks/chunk-E2ZSLTOP.js +0 -2
  162. package/dist/cli-bundle/chunks/chunk-FB7G2HY2.js +0 -2
  163. package/dist/cli-bundle/chunks/chunk-H5Y5YE6A.js +0 -2
  164. package/dist/cli-bundle/chunks/chunk-H5Y6UV6E.js +0 -2
  165. package/dist/cli-bundle/chunks/chunk-H7KGWPDF.js +0 -2
  166. package/dist/cli-bundle/chunks/chunk-HFSD77TQ.js +0 -2
  167. package/dist/cli-bundle/chunks/chunk-HX2GTA6L.js +0 -2
  168. package/dist/cli-bundle/chunks/chunk-J2IEKAVR.js +0 -2
  169. package/dist/cli-bundle/chunks/chunk-JC6FKIFM.js +0 -2
  170. package/dist/cli-bundle/chunks/chunk-K44PYFXH.js +0 -2
  171. package/dist/cli-bundle/chunks/chunk-K4KGEEBT.js +0 -2
  172. package/dist/cli-bundle/chunks/chunk-KFLK5TRH.js +0 -21
  173. package/dist/cli-bundle/chunks/chunk-KL6IEBV2.js +0 -2
  174. package/dist/cli-bundle/chunks/chunk-KWQZDZSS.js +0 -2
  175. package/dist/cli-bundle/chunks/chunk-KZ4X3DGU.js +0 -3
  176. package/dist/cli-bundle/chunks/chunk-LD77HJMQ.js +0 -13
  177. package/dist/cli-bundle/chunks/chunk-LEPJJ6QC.js +0 -2
  178. package/dist/cli-bundle/chunks/chunk-ME2JJ4LA.js +0 -3
  179. package/dist/cli-bundle/chunks/chunk-NE5VRDAI.js +0 -2
  180. package/dist/cli-bundle/chunks/chunk-NFLJ3FHD.js +0 -2
  181. package/dist/cli-bundle/chunks/chunk-NG6OXIBR.js +0 -19
  182. package/dist/cli-bundle/chunks/chunk-NYIGHWQY.js +0 -8
  183. package/dist/cli-bundle/chunks/chunk-NZ75GNSA.js +0 -2
  184. package/dist/cli-bundle/chunks/chunk-PCJWJNC2.js +0 -2
  185. package/dist/cli-bundle/chunks/chunk-PD3225AM.js +0 -2
  186. package/dist/cli-bundle/chunks/chunk-PDEGKG7P.js +0 -2
  187. package/dist/cli-bundle/chunks/chunk-PIE5HBNA.js +0 -2
  188. package/dist/cli-bundle/chunks/chunk-PW2H7YJR.js +0 -56
  189. package/dist/cli-bundle/chunks/chunk-RSIC5OPE.js +0 -2
  190. package/dist/cli-bundle/chunks/chunk-TPKN3S7S.js +0 -2
  191. package/dist/cli-bundle/chunks/chunk-TPXAXTCO.js +0 -2
  192. package/dist/cli-bundle/chunks/chunk-UFWUJO4V.js +0 -2
  193. package/dist/cli-bundle/chunks/chunk-UQLZQVFW.js +0 -55
  194. package/dist/cli-bundle/chunks/chunk-VT3Z5G7D.js +0 -2
  195. package/dist/cli-bundle/chunks/chunk-WOD3WWUN.js +0 -2
  196. package/dist/cli-bundle/chunks/chunk-WSJEIGJF.js +0 -3
  197. package/dist/cli-bundle/chunks/chunk-WYNUU7ZW.js +0 -2008
  198. package/dist/cli-bundle/chunks/chunk-YGPNCCXZ.js +0 -2
  199. package/dist/cli-bundle/chunks/close-CMY3BAUG.js +0 -2
  200. package/dist/cli-bundle/chunks/close-many-SA4XZCTK.js +0 -2
  201. package/dist/cli-bundle/chunks/comments-EZ556ZD3.js +0 -2
  202. package/dist/cli-bundle/chunks/copy-ZSGPA52X.js +0 -2
  203. package/dist/cli-bundle/chunks/create-I5DVV4YG.js +0 -2
  204. package/dist/cli-bundle/chunks/delete-RL3JACSW.js +0 -2
  205. package/dist/cli-bundle/chunks/deps-S7UBCECS.js +0 -2
  206. package/dist/cli-bundle/chunks/docs-ZZNVBBYO.js +0 -2
  207. package/dist/cli-bundle/chunks/files-27C337VT.js +0 -2
  208. package/dist/cli-bundle/chunks/focus-5Z2SG7LU.js +0 -2
  209. package/dist/cli-bundle/chunks/history-compact-HJQK67CZ.js +0 -2
  210. package/dist/cli-bundle/chunks/history-redact-PWC6PDWA.js +0 -2
  211. package/dist/cli-bundle/chunks/history-repair-N3CY4WBF.js +0 -2
  212. package/dist/cli-bundle/chunks/learnings-4FH23XDT.js +0 -2
  213. package/dist/cli-bundle/chunks/profile-5Y5XXH5N.js +0 -2
  214. package/dist/cli-bundle/chunks/register-mutation-YGYPW3BL.js +0 -20
  215. package/dist/cli-bundle/chunks/register-operations-WMDSUMQF.js +0 -2
  216. package/dist/cli-bundle/chunks/register-setup-DL7FFABC.js +0 -2
  217. package/dist/cli-bundle/chunks/restore-6KYBV5BY.js +0 -2
  218. package/dist/cli-bundle/chunks/schema-EQGKBYXJ.js +0 -2
  219. package/dist/cli-bundle/chunks/update-QVTYOD6I.js +0 -2
  220. package/dist/cli-bundle/chunks/update-many-DJSBU525.js +0 -2
  221. package/dist/cli-bundle/focused-chunks/chunk-2ECLECMK.js +0 -12
  222. package/dist/cli-bundle/focused-chunks/chunk-4EX25PXM.js +0 -8
  223. package/dist/cli-bundle/focused-chunks/chunk-DLTS3IHM.js +0 -2
  224. package/dist/cli-bundle/focused-chunks/chunk-DQ6FKGL3.js +0 -14
  225. package/dist/cli-bundle/focused-chunks/chunk-JLG2C4EQ.js +0 -2
  226. package/dist/cli-bundle/focused-chunks/chunk-ZJIMJHDB.js +0 -2
package/docs/RELEASING.md CHANGED
@@ -21,7 +21,10 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
21
21
  [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), stable peer compatibility
22
22
  [pm-csuce0](../.agents/pm/issues/pm-csuce0.toon), and artifact budgets
23
23
  [pm-998juj](../.agents/pm/tasks/pm-998juj.toon), plus exact-tag recovery
24
- [pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon).
24
+ [pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon), and SDK-bound reliability
25
+ classification [pm-dqtzva](../.agents/pm/issues/pm-dqtzva.toon).
26
+ The local/hosted gate selection contract is tracked by
27
+ [pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon).
25
28
 
26
29
  ## Version Policy
27
30
 
@@ -177,6 +180,16 @@ Run the public Sentry/telemetry threshold gate through the package script alias:
177
180
  pnpm sentry:telemetry:gate -- --telemetry-mode best-effort
178
181
  ```
179
182
 
183
+ The Sentry threshold gate reads the latest event for each issue and classifies
184
+ expected handled failures from the SDK error catalog. An event is ignored only
185
+ when it is handled, its `pm.error_code` resolves to a declared canonical code,
186
+ its `pm.exit_code` exactly matches that code's transport contract, and the
187
+ semantic class is `usage`, `not_found`, or `conflict`. Message and title prose
188
+ never participate. Unknown codes, missing or mismatched exits, unhandled
189
+ events, and every `generic_failure` or `dependency_failed` remain blocking.
190
+ This keeps rewording independent from release policy and makes stale or broad
191
+ message allowlists impossible.
192
+
180
193
  If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
181
194
 
182
195
  The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256 digests for every emitted bundle file. At startup, `pm` reports `bundle_integrity_torn_install` only when a module-loader failure is accompanied by manifest proof that an upgrade or rebuild changed, removed, or corrupted the active bundle. Reinstall `@unbrained/pm-cli` and retry after that diagnostic. Ordinary `ERR_MODULE_NOT_FOUND` and export failures with an intact manifest remain unexpected failures and must continue to block reliability gates.
@@ -184,7 +197,19 @@ The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256
184
197
  4. Run the same release pipeline locally.
185
198
 
186
199
  Push the final implementation commit first, wait for DeepScan and CodeFactor to
187
- finish on that reviewed SHA, and run the mandatory local hosted-analysis proof:
200
+ finish on that reviewed SHA, then run the canonical registry-owned preflight:
201
+
202
+ ```bash
203
+ pnpm verify:preflight
204
+ ```
205
+
206
+ The registry supplies the ordered executable plan, command arguments,
207
+ environment, capture policy, and explicit skip policy. Its receipt distinguishes
208
+ passed checks from declared skips. The same registry maps named PR, nightly,
209
+ and release workflow gates; hosted-only entries must explain why no faithful
210
+ local equivalent exists.
211
+
212
+ The preflight includes the mandatory local hosted-analysis proof:
188
213
 
189
214
  ```bash
190
215
  pnpm quality:hosted-analysis
package/docs/SCRIPTING.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # CLI Scripting Contract
2
2
 
3
- Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
3
+ Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-hqa8g1](../.agents/pm/tasks/pm-hqa8g1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
4
4
 
5
5
  Use this contract when composing `pm` with shells, CI runners, `jq`, or another process. Exact flags remain discoverable from `pm <command> --help --json` and `pm contracts --command <command> --flags-only --json`.
6
6
 
@@ -14,6 +14,32 @@ Use this contract when composing `pm` with shells, CI runners, `jq`, or another
14
14
  | `3` | Requested tracker or resource was not found. | Correct the path or ID. |
15
15
  | `4` | State or concurrency conflict. | Refresh live state before deciding whether to retry. |
16
16
  | `5` | A required dependency operation failed. | Inspect the dependency evidence before retrying. |
17
+ | `6` | The request succeeded but matched nothing to change. | Treat as success and inspect the effect receipt. |
18
+ | `7` | The request succeeded and changed only part of the selected targets. | Treat as success and inspect unmatched/skipped rows. |
19
+
20
+ Exits `0`, `6`, and `7` are successful outcomes. Bulk mutation envelopes repeat
21
+ the distinction as `outcome: effect`, `outcome: no_effect`, or `outcome:
22
+ partial_effect` with the same `exit_code`. Because POSIX shells treat every
23
+ nonzero exit as a false condition, scripts invoking effect-aware bulk commands
24
+ must preserve and classify the status explicitly rather than relying on a bare
25
+ `if` condition:
26
+
27
+ ```bash
28
+ set +e
29
+ result=$(pm update-many --ids "$ids" --tags reviewed --json)
30
+ status=$?
31
+ set -e
32
+
33
+ case "$status" in
34
+ 0|6|7) printf '%s\n' "$result" | jq '{outcome, matched_count, updated_count}' ;;
35
+ *) printf '%s\n' "pm update-many failed with exit $status" >&2; exit "$status" ;;
36
+ esac
37
+ ```
38
+
39
+ The generated contract is authoritative. `pm contracts --command update-many
40
+ --full --json` returns `command_exit_contracts.vocabulary` and the selected
41
+ command's exhaustive `exit_codes`; SDK consumers can use the same declarations
42
+ and `isPmSuccessfulExitCode` from `@unbrained/pm-cli/sdk/contracts`.
17
43
 
18
44
  Successful structured results are written to stdout. Diagnostics, warnings, profiles, and errors are written to stderr so `--json`, `--format ndjson`, CSV, and table stdout remain pipe-safe. Never merge stderr into stdout before parsing structured output.
19
45
 
@@ -0,0 +1,66 @@
1
+ # SDK Context Integrity
2
+
3
+ Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), and [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon).
4
+
5
+ ## Agent Quick Context
6
+
7
+ These contracts keep project management equal to context management: reads say what they omit, writes return only newly useful context, diagnostics do not unexpectedly call remote providers, and every transport delegates domain validation to the same SDK primitive. Package authors can use the same primitives without reproducing CLI parsing rules.
8
+
9
+ ## `get` output selectors
10
+
11
+ `pm get` has one declared selector namespace. Top-level sections use their names, while item fields may be written as either a bare field or `item.<field>`:
12
+
13
+ ```bash
14
+ pm get pm-a1b2 --output-include id,title
15
+ pm get pm-a1b2 --output-include item.id,item.title,linked
16
+ pm get pm-a1b2 --output-include item,claim_state
17
+ ```
18
+
19
+ An unknown selector is a usage refusal that lists the valid vocabulary. Selecting the complete `item` object together with an item field is also refused because the two selectors express conflicting projection depths. Every successful projection carries an `omission_receipt` with the exact selectors needed to restore withheld item fields or sections.
20
+
21
+ ## Bounded annotation mutations
22
+
23
+ Adding, editing, or deleting a comment, note, or learning returns the changed entry plus mutation and omission receipts. The reply size therefore stays independent of the item’s existing annotation history. Pass `--full-history` when a human or integration genuinely needs the complete post-mutation collection:
24
+
25
+ ```bash
26
+ pm comments pm-a1b2 "Decision evidence"
27
+ pm comments pm-a1b2 --edit 3 --message "Corrected evidence" --full-history
28
+ pm notes pm-a1b2 --delete 2 --full-history
29
+ ```
30
+
31
+ SDK callers use `fullHistory: true`; MCP callers use `full: true`. The default stays bounded on every transport. An omission receipt identifies the semantic `full_history` selector and includes its CLI (`--full-history`), SDK (`fullHistory`), and MCP (`full`) spellings, so non-CLI consumers never need to interpret shell-only guidance.
32
+
33
+ ## Author acknowledgment coordinates
34
+
35
+ CLI, SDK, and MCP use the same selector and coordinate parser for `history-author-acknowledge`. A coordinate is `<item-id>:<line>` or `_workspace:<line>`, with a positive one-based line number. Exactly one of explicit events or `all_actionable` is required.
36
+
37
+ ```bash
38
+ pm history-author-acknowledge \
39
+ --event _workspace:4 \
40
+ --attributed-author import-agent \
41
+ --reviewer maintainer \
42
+ --reason "Verified workspace provenance"
43
+ ```
44
+
45
+ The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar.
46
+
47
+ ## Health provider boundary
48
+
49
+ `pm health` is read-only by default and never refreshes embeddings merely because a semantic provider is configured. Provider I/O requires `--refresh-vectors`; `--skip-vectors` or `--no-refresh` records the explicit non-provider path. Provider requests remain bounded by the configured embedding timeout, and a failed refresh reports the responsible vector diagnostic plus the skip remediation.
50
+
51
+ ## Replication and refusal gate
52
+
53
+ `scripts/release/surface-replication-sets.json` declares replicated SDK, CLI, MCP, documentation, and test members. `pnpm quality:surface-replication` activates sets from the Git changeset, verifies every member invariant, and reports:
54
+
55
+ - active set recurrence density;
56
+ - the largest source member’s utilization of the mandatory file-size cap;
57
+ - every remaining CLI-owned `PmCliError`, grouped by an explicit adapter-level disposition;
58
+ - applied waivers, including their PM owner and expiry.
59
+
60
+ Query waivers directly with:
61
+
62
+ ```bash
63
+ node scripts/release/surface-replication-gate.mjs --list-waivers
64
+ ```
65
+
66
+ Waivers are never implicit: they require a canonical PM item, a reason, an exact set member, and an expiry date. New or moved CLI refusals fail until the inventory is updated or the rule is delegated into the SDK. The same declaration runs locally and inside the required static-quality workflow.
@@ -0,0 +1,58 @@
1
+ # SDK Runtime Boundaries
2
+
3
+ Tracker: [pm-1eted6](../.agents/pm/issues/pm-1eted6.toon),
4
+ [pm-3lhth4](../.agents/pm/issues/pm-3lhth4.toon), and
5
+ [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon).
6
+
7
+ These SDK primitives keep host and project-runtime policy consistent across the
8
+ bundled CLI, packages, and automation without requiring consumers to reproduce
9
+ private CLI parsing rules.
10
+
11
+ ## Project runtime compatibility
12
+
13
+ Packages and automation can call `inspectProjectRuntimeCompatibility` before a
14
+ mutation, or `assertProjectRuntimeCompatibility` when refusal semantics are
15
+ preferred. The SDK discovers the strongest project-local pm version pin from
16
+ the package manifest, installed package metadata, and supported lockfiles. A
17
+ CLI older than that pin refuses mutation with
18
+ `project_runtime_stale_mutation`; read commands stay available so an agent can
19
+ recover context before upgrading. Stale reads, including `context` and
20
+ read-only `health` invocations, emit the non-blocking
21
+ `project_runtime_stale_read` warning. JSON modes write a single structured
22
+ warning object to stderr, leaving the command's normal stdout envelope valid;
23
+ human modes identify both versions, the redaction-safe pin source, and a
24
+ package-manager-neutral recovery action. SDK callers receive the same warning
25
+ inside `ProjectRuntimeCompatibilityResult`. `PM_ALLOW_STALE_CLI=1` is the
26
+ explicit, auditable emergency override.
27
+
28
+ The public `isProjectMutatingInvocation` classifier applies the same decision
29
+ to package hosts and the bundled CLI. It resolves mixed command families by
30
+ their effective action: configuration, merge, schema, profile, package,
31
+ telemetry, workspace snapshot, template, VCS, validation, health, test, linked
32
+ artifact, and changelog reads remain available while their write forms are
33
+ fenced. Help, checks, previews, and dry runs remain reads, so compatibility
34
+ enforcement does not turn diagnostics into writes.
35
+
36
+ ## Host-environment fault boundary
37
+
38
+ Use `withHostEnvironmentBoundary` around filesystem and resource operations
39
+ that cross into the host. It translates recognized Node errno failures into
40
+ the stable, path-redacted `host_environment_capacity_fault`,
41
+ `host_environment_permission_fault`, or `host_environment_resource_fault`
42
+ contracts. `classifyHostEnvironmentFault` supports diagnostics that need a
43
+ non-throwing classification, while `translateHostEnvironmentFault` supports an
44
+ existing catch boundary. Non-errno failures are returned unchanged and must
45
+ not be relabeled as environment faults.
46
+
47
+ Existing SDK surfaces can supply category-specific `codes` to preserve their
48
+ published error vocabulary while still sharing classification, path redaction,
49
+ and recovery guidance. Workspace snapshots use this compatibility path for
50
+ their stable storage, resource, and permission fault codes.
51
+
52
+ ## CLI refusal ownership
53
+
54
+ CLI adapters preserve SDK error codes, exit semantics, and actionable recovery
55
+ guidance when presenting refusals as human-readable or structured output.
56
+ Host-only validation remains at the transport boundary, while rules shared by
57
+ packages and commands live in public SDK primitives so callers receive the
58
+ same refusal contract regardless of entrypoint.
@@ -79,6 +79,7 @@ The default summary stays bounded. Larger intent and error catalogs are emitted
79
79
  - recovery guidance;
80
80
  - source modules that emit the code.
81
81
  - inferred CLI command roots (`*` for cross-cutting runtime failures).
82
+ - canonical code and compatibility aliases for concept-level handling.
82
83
 
83
84
  Existing catalog entries are recorded in `scripts/error-code-stability.json`.
84
85
  The generator refuses to remove one of those stable codes unless the reviewed
@@ -86,6 +87,18 @@ compatibility ledger is changed explicitly. Newly discovered codes are emitted
86
87
  as provisional until deliberately promoted, so adding a runtime declaration
87
88
  does not accidentally promise permanent compatibility.
88
89
 
90
+ The compatibility ledger also pins every stable code to its reviewed process
91
+ exit. An executable `PmCliError` declaration that disagrees with that mapping
92
+ fails generation, and a stable code without a mapping fails the drift check.
93
+ Reviewed alias groups preserve every emitted legacy spelling while exposing one
94
+ canonical concept to SDK, package, CLI-contract, and observability consumers.
95
+ Aliases must resolve directly to a declared stable canonical code and share its
96
+ exit class; cycles, missing targets, and transport mismatches fail closed.
97
+
98
+ Use `resolvePmErrorCodeContract` when the exact emitted spelling matters, and
99
+ `resolveCanonicalPmErrorCodeContract` when one handler should cover a complete
100
+ compatibility group.
101
+
89
102
  `PM_ERROR_CODE_EXIT_CLASS_CONTRACTS` is the portable shell taxonomy: exit 1 is
90
103
  generic failure, 2 is usage, 3 is not-found, 4 is conflict, and 5 is dependency
91
104
  failure. Catalog validation rejects a code whose declared semantic class and
package/docs/TESTING.md CHANGED
@@ -16,6 +16,8 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
16
16
 
17
17
  Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
18
18
 
19
+ Local/hosted gate parity is tracked by [pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon).
20
+
19
21
  ## Standard Local Checks
20
22
 
21
23
  ```bash
@@ -26,6 +28,21 @@ node scripts/run-tests.mjs test
26
28
  node scripts/run-tests.mjs coverage
27
29
  ```
28
30
 
31
+ For the exact ordered local preflight used to make release-readiness claims,
32
+ run the registry-owned entrypoint:
33
+
34
+ ```bash
35
+ pnpm verify:preflight
36
+ ```
37
+
38
+ `scripts/release/gate-registry.json` is the executable plan for this command:
39
+ each ordered step declares its command, arguments, environment, capture mode,
40
+ and whether an explicit skip flag is permitted. Receipts distinguish passed
41
+ steps from declared skips, and `quality:gate-registry` maps hosted workflow
42
+ claims to the same canonical gate IDs. Hosted-only environment isolation and
43
+ tracker-integrity steps remain explicit entries with reasons rather than
44
+ silently disappearing from local parity.
45
+
29
46
  `node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
30
47
 
31
48
  Public SDK changes additionally run semantic surface and import-cost contracts:
package/marketplace.json CHANGED
@@ -6,14 +6,14 @@
6
6
  },
7
7
  "metadata": {
8
8
  "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
9
- "version": "2026.8.7"
9
+ "version": "2026.8.8"
10
10
  },
11
11
  "plugins": [
12
12
  {
13
13
  "name": "pm-claude",
14
14
  "source": "./plugins/pm-claude",
15
15
  "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.",
16
- "version": "2026.8.7",
16
+ "version": "2026.8.8",
17
17
  "author": {
18
18
  "name": "unbrained",
19
19
  "url": "https://github.com/unbraind/pm-cli"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-cli",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "description": "Git-native project management CLI for humans and agents.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
120
120
  "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
121
121
  "lint:duplicates": "jscpd --config .jscpd.json",
122
122
  "lint:codefactor": "pnpm quality:static",
123
- "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
123
+ "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
124
124
  "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
125
125
  "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
126
126
  "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -132,6 +132,7 @@
132
132
  "quality:gate-registry": "pnpm build && node scripts/release/gate-registry.mjs",
133
133
  "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
134
134
  "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
135
+ "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
135
136
  "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
136
137
  "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
137
138
  "quality:hosted-analysis": "node scripts/release/hosted-analysis-gate.mjs",
@@ -163,6 +164,7 @@
163
164
  "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
164
165
  "release:notes": "node scripts/generate-release-notes.mjs",
165
166
  "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
167
+ "verify:preflight": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
166
168
  "release:pipeline": "node scripts/release/run-release-pipeline.mjs",
167
169
  "release:pipeline:dry-run": "node scripts/release/run-release-pipeline.mjs --dry-run",
168
170
  "release:verify-published": "node scripts/release/verify-published-release.mjs",
@@ -218,7 +220,7 @@
218
220
  "fast-check": "^4.9.0",
219
221
  "greptile": "^3.3.1",
220
222
  "jscpd": "^5.0.14",
221
- "tsx": "^4.23.8",
223
+ "tsx": "^4.23.11",
222
224
  "typescript": "^6.0.3",
223
225
  "typescript-eslint": "^8.66.0",
224
226
  "vitest": "^4.1.10",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-beads",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for importing Beads JSONL records.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-calendar",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for calendar and agenda views.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-command-kit",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-digital-twin",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-governance-audit",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for governance audit and normalization workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-guide-shell",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for guide and shell completion workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-kanban",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-lifecycle-hooks",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package demonstrating safe lifecycle hook registration.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-linked-test-adapters",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for optional linked-test run management adapters and reporters.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-search-advanced",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-templates",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for reusable create templates.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-todos",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for Todo markdown import and export.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-vcs-sdk-exemplar",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pm-claude",
3
3
  "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
4
- "version": "2026.8.7",
4
+ "version": "2026.8.8",
5
5
  "author": {
6
6
  "name": "unbrained",
7
7
  "url": "https://github.com/unbraind/pm-cli"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pm-codex",
3
- "version": "2026.8.7",
3
+ "version": "2026.8.8",
4
4
  "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
5
5
  "author": {
6
6
  "name": "unbrained",