@unbrained/pm-cli 2026.9.3 → 2026.9.5

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 (228) hide show
  1. package/.agents/skills/HARNESS_COMPATIBILITY.md +1 -1
  2. package/.agents/skills/README.md +2 -2
  3. package/.agents/skills/pm-developer/SKILL.md +4 -1
  4. package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md +10 -0
  5. package/.agents/skills/pm-developer/references/GRAPH_AND_RELATIONSHIPS.md +3 -1
  6. package/.agents/skills/pm-extensions/SKILL.md +2 -2
  7. package/.agents/skills/pm-extensions/references/LIFECYCLE.md +3 -3
  8. package/.agents/skills/pm-extensions/references/TROUBLESHOOTING.md +3 -3
  9. package/.agents/skills/pm-user/SKILL.md +2 -0
  10. package/.agents/skills/pm-user/references/BACKLOG_SHAPING.md +5 -0
  11. package/.agents/skills/pm-user/references/WORKFLOWS.md +20 -5
  12. package/.claude-plugin/marketplace.json +2 -2
  13. package/CHANGELOG.md +52 -0
  14. package/dist/cli/commander-usage.d.ts +2 -0
  15. package/dist/cli/commander-usage.js +15 -12
  16. package/dist/cli/help-json-payload.js +12 -7
  17. package/dist/cli/main.js +15 -6
  18. package/dist/cli/register-list-query.js +4 -2
  19. package/dist/cli/register-mutation.js +4 -2
  20. package/dist/cli/register-operations.js +6 -2
  21. package/dist/cli-bundle/bundle-manifest.json +154 -154
  22. package/dist/cli-bundle/chunks/{chunk-EDPIS7EB.js → chunk-3HBDTJRK.js} +2 -2
  23. package/dist/cli-bundle/chunks/chunk-66VPKFP2.js +5 -0
  24. package/dist/cli-bundle/chunks/{chunk-Y4PJ6HPK.js → chunk-HUAQITVW.js} +2 -2
  25. package/dist/cli-bundle/chunks/{chunk-DKGP3QLE.js → chunk-IBYREGSP.js} +2 -2
  26. package/dist/cli-bundle/chunks/chunk-LUI4E32I.js +231 -0
  27. package/dist/cli-bundle/chunks/{chunk-UPPM2FOZ.js → chunk-QPZHQY2O.js} +2 -2
  28. package/dist/cli-bundle/chunks/{chunk-34HASX3S.js → chunk-SF6SM6U5.js} +2 -2
  29. package/dist/cli-bundle/chunks/chunk-SVK5Y64D.js +40 -0
  30. package/dist/cli-bundle/chunks/chunk-V5GBD5KV.js +9 -0
  31. package/dist/cli-bundle/chunks/{chunk-LENC656S.js → chunk-WWAEGW4V.js} +67 -70
  32. package/dist/cli-bundle/chunks/chunk-ZRAQS3UA.js +8 -0
  33. package/dist/cli-bundle/chunks/{register-list-query-W2ZTOMKP.js → register-list-query-AYKGODWT.js} +3 -3
  34. package/dist/cli-bundle/chunks/{register-mutation-RVND5NCG.js → register-mutation-YZYG53SQ.js} +4 -4
  35. package/dist/cli-bundle/chunks/register-operations-KFSCC7QV.js +2 -0
  36. package/dist/cli-bundle/chunks/{register-setup-D3ZFHY3L.js → register-setup-UJCRVGBG.js} +2 -2
  37. package/dist/cli-bundle/focused-chunks/chunk-24IG6ONG.js +2 -0
  38. package/dist/cli-bundle/focused-chunks/{chunk-M5M6SVHS.js → chunk-3ASU6WGI.js} +2 -2
  39. package/dist/cli-bundle/focused-chunks/chunk-3ITLIBKS.js +56 -0
  40. package/dist/cli-bundle/focused-chunks/chunk-3NQD5YDG.js +2 -0
  41. package/dist/cli-bundle/focused-chunks/{chunk-S27XMBIN.js → chunk-4OSHLNUE.js} +2 -2
  42. package/dist/cli-bundle/focused-chunks/chunk-65N6JHAN.js +2 -0
  43. package/dist/cli-bundle/focused-chunks/{chunk-5RFXUPN5.js → chunk-B2TTQGFG.js} +2 -2
  44. package/dist/cli-bundle/focused-chunks/chunk-GUBM3RGY.js +20 -0
  45. package/dist/cli-bundle/focused-chunks/{chunk-Q45NHPF2.js → chunk-H5FOGAVD.js} +2 -2
  46. package/dist/cli-bundle/focused-chunks/chunk-JX3RCVCX.js +2 -0
  47. package/dist/cli-bundle/focused-chunks/{chunk-D7KXFBXV.js → chunk-KWWCBWFO.js} +2 -2
  48. package/dist/cli-bundle/focused-chunks/chunk-MV752SUC.js +12 -0
  49. package/dist/cli-bundle/focused-chunks/chunk-PKIPMCFS.js +6 -0
  50. package/dist/cli-bundle/focused-chunks/{chunk-4HJFY4MB.js → chunk-QL66QNWG.js} +2 -2
  51. package/dist/cli-bundle/focused-chunks/chunk-RJMR2JIF.js +9 -0
  52. package/dist/cli-bundle/focused-chunks/chunk-WIUPWIZR.js +177 -0
  53. package/dist/cli-bundle/focused-chunks/chunk-WOCIPMW7.js +2 -0
  54. package/dist/cli-bundle/focused-chunks/{chunk-GT7MXDLW.js → chunk-YEF5PQQ2.js} +2 -2
  55. package/dist/cli-bundle/main.js +22 -15
  56. package/dist/cli-bundle/sdk-authoring.js +1 -1
  57. package/dist/cli-bundle/sdk-contracts.js +1 -1
  58. package/dist/cli-bundle/sdk-core.js +29 -32
  59. package/dist/cli-bundle/sdk-governance.js +1 -1
  60. package/dist/cli-bundle/sdk-graph.js +1 -1
  61. package/dist/cli-bundle/sdk-merge.js +45 -37
  62. package/dist/cli-bundle/sdk-query.js +1 -1
  63. package/dist/cli-bundle/sdk-runtime.js +1 -1
  64. package/dist/cli-bundle/sdk-testing.js +1 -1
  65. package/dist/cli-bundle/sdk.js +10 -10
  66. package/dist/core/diagnostics/remediation.js +4 -4
  67. package/dist/core/extensions/extension-types.d.ts +2 -0
  68. package/dist/core/extensions/extension-types.js +2 -2
  69. package/dist/core/history/drift-scan.d.ts +5 -0
  70. package/dist/core/history/drift-scan.js +16 -6
  71. package/dist/core/history/event-classification.d.ts +1 -1
  72. package/dist/core/history/event-classification.js +3 -2
  73. package/dist/core/history/history.d.ts +37 -1
  74. package/dist/core/history/history.js +311 -59
  75. package/dist/core/history/identity.d.ts +15 -0
  76. package/dist/core/history/identity.js +31 -0
  77. package/dist/core/history/projection.js +50 -17
  78. package/dist/core/history/read.js +6 -3
  79. package/dist/core/history/replay.d.ts +1 -2
  80. package/dist/core/history/replay.js +70 -36
  81. package/dist/core/history/version-address.d.ts +13 -0
  82. package/dist/core/history/version-address.js +33 -0
  83. package/dist/core/item/actionability.d.ts +21 -1
  84. package/dist/core/item/actionability.js +45 -10
  85. package/dist/core/item/id.js +8 -4
  86. package/dist/core/item/item-type-definition.d.ts +2 -0
  87. package/dist/core/item/item-type-definition.js +9 -2
  88. package/dist/core/item/type-registry.d.ts +5 -1
  89. package/dist/core/item/type-registry.js +9 -4
  90. package/dist/core/lock/lock.d.ts +10 -0
  91. package/dist/core/lock/lock.js +42 -3
  92. package/dist/core/shared/author.d.ts +3 -1
  93. package/dist/core/shared/author.js +111 -23
  94. package/dist/core/shared/errors.d.ts +8 -0
  95. package/dist/core/shared/errors.js +2 -2
  96. package/dist/core/store/item-store.d.ts +14 -0
  97. package/dist/core/store/item-store.js +48 -10
  98. package/dist/core/store/settings-validator.js +3 -2
  99. package/dist/sdk/actionability.d.ts +1 -1
  100. package/dist/sdk/actionability.js +3 -3
  101. package/dist/sdk/cli-contracts/command-aliases.js +11 -2
  102. package/dist/sdk/cli-contracts/completeness.js +4 -3
  103. package/dist/sdk/cli-contracts/flag-contracts.js +29 -5
  104. package/dist/sdk/cli-contracts/flag-lexicon-contracts.js +19 -12
  105. package/dist/sdk/cli-contracts/tool-parameter-tables.js +14 -2
  106. package/dist/sdk/cli-contracts/tool-schema.d.ts +2 -2
  107. package/dist/sdk/cli-contracts/tool-schema.js +19 -6
  108. package/dist/sdk/context-intent-contracts.js +3 -3
  109. package/dist/sdk/context-usage.js +9 -11
  110. package/dist/sdk/define.d.ts +1 -1
  111. package/dist/sdk/define.js +2 -2
  112. package/dist/sdk/environment/agent-environment.d.ts +296 -0
  113. package/dist/sdk/environment/agent-environment.js +467 -0
  114. package/dist/sdk/environment/project-runtime-compatibility.d.ts +19 -1
  115. package/dist/sdk/environment/project-runtime-compatibility.js +118 -21
  116. package/dist/sdk/generated/generated-error-code-catalog-part-1.js +98 -38
  117. package/dist/sdk/generated/generated-error-code-catalog-part-2.js +50 -2
  118. package/dist/sdk/governance/health.js +13 -44
  119. package/dist/sdk/governance/merge-receipt-history.d.ts +62 -0
  120. package/dist/sdk/governance/merge-receipt-history.js +207 -0
  121. package/dist/sdk/governance/provenance-health.js +9 -3
  122. package/dist/sdk/governance/validate-history-drift.js +16 -5
  123. package/dist/sdk/guide-topics.js +116 -2
  124. package/dist/sdk/history/salvage.d.ts +35 -0
  125. package/dist/sdk/history/salvage.js +248 -0
  126. package/dist/sdk/history-compact.js +41 -37
  127. package/dist/sdk/history-read.d.ts +3 -2
  128. package/dist/sdk/history-read.js +6 -3
  129. package/dist/sdk/history-redact.js +58 -23
  130. package/dist/sdk/history-repair.d.ts +5 -0
  131. package/dist/sdk/history-repair.js +28 -6
  132. package/dist/sdk/index.d.ts +2 -0
  133. package/dist/sdk/index.js +4 -2
  134. package/dist/sdk/lifecycle/claim.d.ts +4 -0
  135. package/dist/sdk/lifecycle/claim.js +9 -3
  136. package/dist/sdk/lifecycle/restore.d.ts +1 -0
  137. package/dist/sdk/lifecycle/restore.js +19 -7
  138. package/dist/sdk/merge/driver.d.ts +3 -1
  139. package/dist/sdk/merge/driver.js +9 -9
  140. package/dist/sdk/merge/index.d.ts +1 -1
  141. package/dist/sdk/merge/index.js +3 -3
  142. package/dist/sdk/merge/receipts.d.ts +17 -6
  143. package/dist/sdk/merge/receipts.js +246 -75
  144. package/dist/sdk/merge/reconcile.d.ts +9 -7
  145. package/dist/sdk/merge/reconcile.js +175 -12
  146. package/dist/sdk/merge/three-way.d.ts +22 -2
  147. package/dist/sdk/merge/three-way.js +92 -25
  148. package/dist/sdk/output-projection.d.ts +3 -1
  149. package/dist/sdk/output-projection.js +11 -3
  150. package/dist/sdk/public-surface.json +1 -0
  151. package/dist/sdk/query/context.d.ts +9 -0
  152. package/dist/sdk/query/context.js +33 -21
  153. package/dist/sdk/query/get.d.ts +2 -2
  154. package/dist/sdk/query/get.js +4 -3
  155. package/dist/sdk/query/history.d.ts +11 -0
  156. package/dist/sdk/query/history.js +34 -10
  157. package/dist/sdk/query/next.d.ts +15 -1
  158. package/dist/sdk/query/next.js +43 -20
  159. package/dist/sdk/query.d.ts +1 -0
  160. package/dist/sdk/query.js +3 -2
  161. package/dist/sdk/runtime-primitives.d.ts +3 -3
  162. package/dist/sdk/runtime-primitives.js +5 -5
  163. package/dist/types.d.ts +27 -0
  164. package/dist/types.js +2 -2
  165. package/docs/AGENT_ENVIRONMENTS.md +47 -0
  166. package/docs/AGENT_GUIDE.md +36 -0
  167. package/docs/AGENT_PROVENANCE_ADR.md +17 -2
  168. package/docs/CONTEXT_INTEGRITY_CONTRACTS.md +38 -1
  169. package/docs/HISTORY_RECOVERY.md +146 -0
  170. package/docs/MERGE_SAFETY.md +119 -23
  171. package/docs/README.md +2 -0
  172. package/docs/RELEASING.md +25 -11
  173. package/docs/SDK_CONTEXT_EVIDENCE_CONTRACTS.md +24 -2
  174. package/docs/SDK_CONTEXT_TRUTH_CONTRACTS.md +24 -1
  175. package/docs/SDK_EXECUTION_CONTRACTS.md +105 -0
  176. package/docs/SDK_RUNTIME_BOUNDARIES.md +17 -1
  177. package/docs/TESTING.md +5 -0
  178. package/docs/agent-task-token-baseline.json +17 -17
  179. package/docs/agent-task-transcripts.json +2 -1
  180. package/docs/examples/sdk-agent-environment/README.md +14 -0
  181. package/docs/examples/sdk-agent-environment/package.json +8 -0
  182. package/docs/examples/sdk-agent-environment/run-agent-environment.mjs +154 -0
  183. package/docs/generated/FLAG_LEXICON_BUDGETS.md +10 -10
  184. package/docs/generated/REFUSAL_CLOSURE_CENSUS.md +12 -3
  185. package/marketplace.json +2 -2
  186. package/package.json +5 -6
  187. package/packages/pm-beads/package.json +1 -1
  188. package/packages/pm-calendar/package.json +1 -1
  189. package/packages/pm-command-kit/package.json +1 -1
  190. package/packages/pm-digital-twin/package.json +1 -1
  191. package/packages/pm-governance-audit/package.json +1 -1
  192. package/packages/pm-guide-shell/package.json +1 -1
  193. package/packages/pm-kanban/package.json +1 -1
  194. package/packages/pm-lifecycle-hooks/package.json +1 -1
  195. package/packages/pm-linked-test-adapters/package.json +1 -1
  196. package/packages/pm-search-advanced/package.json +1 -1
  197. package/packages/pm-templates/package.json +1 -1
  198. package/packages/pm-todos/package.json +1 -1
  199. package/packages/pm-vcs/package.json +1 -1
  200. package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
  201. package/plugins/pm-claude/skills/pm-audit/SKILL.md +2 -2
  202. package/plugins/pm-claude/skills/pm-developer/SKILL.md +2 -2
  203. package/plugins/pm-claude/skills/pm-planner/SKILL.md +2 -2
  204. package/plugins/pm-claude/skills/pm-release/SKILL.md +2 -2
  205. package/plugins/pm-claude/skills/pm-workflow/SKILL.md +3 -3
  206. package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
  207. package/plugins/pm-codex/skills/pm-auditor/SKILL.md +2 -2
  208. package/plugins/pm-codex/skills/pm-native/SKILL.md +3 -4
  209. package/plugins/pm-codex/skills/pm-release/SKILL.md +2 -2
  210. package/scripts/finalize-build.mjs +13 -1
  211. package/dist/cli-bundle/chunks/chunk-AY324UJ5.js +0 -9
  212. package/dist/cli-bundle/chunks/chunk-E5RBBCXO.js +0 -230
  213. package/dist/cli-bundle/chunks/chunk-IEHHE6GA.js +0 -5
  214. package/dist/cli-bundle/chunks/chunk-L7B7343B.js +0 -8
  215. package/dist/cli-bundle/chunks/chunk-LISESA7W.js +0 -35
  216. package/dist/cli-bundle/chunks/register-operations-TTROIVC4.js +0 -2
  217. package/dist/cli-bundle/focused-chunks/chunk-3ZBI35HU.js +0 -176
  218. package/dist/cli-bundle/focused-chunks/chunk-4RRHC3S4.js +0 -6
  219. package/dist/cli-bundle/focused-chunks/chunk-4WR46RMG.js +0 -9
  220. package/dist/cli-bundle/focused-chunks/chunk-BWKHEIVF.js +0 -2
  221. package/dist/cli-bundle/focused-chunks/chunk-GHCZ3YFR.js +0 -20
  222. package/dist/cli-bundle/focused-chunks/chunk-KBLZRU62.js +0 -2
  223. package/dist/cli-bundle/focused-chunks/chunk-KZ2NB3ET.js +0 -2
  224. package/dist/cli-bundle/focused-chunks/chunk-OL5EH6I3.js +0 -2
  225. package/dist/cli-bundle/focused-chunks/chunk-QKHCSUGJ.js +0 -51
  226. package/dist/cli-bundle/focused-chunks/chunk-TXE4TSHM.js +0 -12
  227. package/dist/cli-bundle/focused-chunks/chunk-UCLO3XDU.js +0 -2
  228. package/sdk/public-surface.json +0 -32524
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 4,
3
3
  "transcript_version": 2,
4
- "transcript_digest": "sha256:4f9e96bb6ce12bbbeb2514e4bd5958d201c4e62e95083bcbebd749d1e48cc82d",
4
+ "transcript_digest": "sha256:b8a6aea318c41e6a40dbcaf8094da8397ca747515a7df249d35c1f21ad94a307",
5
5
  "estimator": "ceil(utf8_bytes / 4)",
6
6
  "measurement_scope": "output_before_token_accounting",
7
7
  "published_with_release": true,
@@ -12,12 +12,12 @@
12
12
  "active_ownership",
13
13
  "workspace_state"
14
14
  ],
15
- "measured_winner_tokens": 1055,
15
+ "measured_winner_tokens": 1102,
16
16
  "protocols": [
17
17
  {
18
18
  "task_id": "orientation-context-intent",
19
19
  "command_count": 1,
20
- "estimated_tokens": 1055,
20
+ "estimated_tokens": 1102,
21
21
  "capabilities": [
22
22
  "actionable_work",
23
23
  "active_ownership",
@@ -47,7 +47,7 @@
47
47
  {
48
48
  "task_id": "orientation-operating-rules",
49
49
  "command_count": 4,
50
- "estimated_tokens": 2293,
50
+ "estimated_tokens": 2340,
51
51
  "capabilities": [
52
52
  "actionable_work",
53
53
  "active_ownership",
@@ -77,7 +77,7 @@
77
77
  {
78
78
  "task_id": "orientation-contracts-next",
79
79
  "command_count": 2,
80
- "estimated_tokens": 4798,
80
+ "estimated_tokens": 4829,
81
81
  "capabilities": [
82
82
  "actionable_work",
83
83
  "active_ownership",
@@ -109,18 +109,18 @@
109
109
  "tasks": [
110
110
  {
111
111
  "id": "orientation-context-intent",
112
- "max_estimated_tokens": 1055,
112
+ "max_estimated_tokens": 1102,
113
113
  "steps": [
114
114
  {
115
115
  "id": "context",
116
- "max_estimated_tokens": 1055,
116
+ "max_estimated_tokens": 1102,
117
117
  "accounting_mode": "self_reported"
118
118
  }
119
119
  ]
120
120
  },
121
121
  {
122
122
  "id": "orientation-contracts-next",
123
- "max_estimated_tokens": 4798,
123
+ "max_estimated_tokens": 4829,
124
124
  "steps": [
125
125
  {
126
126
  "id": "contracts",
@@ -129,18 +129,18 @@
129
129
  },
130
130
  {
131
131
  "id": "next",
132
- "max_estimated_tokens": 687,
132
+ "max_estimated_tokens": 718,
133
133
  "accounting_mode": "self_reported"
134
134
  }
135
135
  ]
136
136
  },
137
137
  {
138
138
  "id": "orientation-operating-rules",
139
- "max_estimated_tokens": 2293,
139
+ "max_estimated_tokens": 2340,
140
140
  "steps": [
141
141
  {
142
142
  "id": "context",
143
- "max_estimated_tokens": 1055,
143
+ "max_estimated_tokens": 1102,
144
144
  "accounting_mode": "self_reported"
145
145
  },
146
146
  {
@@ -162,7 +162,7 @@
162
162
  },
163
163
  {
164
164
  "id": "context-bootstrap",
165
- "max_estimated_tokens": 1978,
165
+ "max_estimated_tokens": 2025,
166
166
  "steps": [
167
167
  {
168
168
  "id": "triage",
@@ -171,7 +171,7 @@
171
171
  },
172
172
  {
173
173
  "id": "orient",
174
- "max_estimated_tokens": 1055,
174
+ "max_estimated_tokens": 1102,
175
175
  "accounting_mode": "self_reported"
176
176
  },
177
177
  {
@@ -199,12 +199,12 @@
199
199
  },
200
200
  {
201
201
  "id": "unknown-option-recovery",
202
- "max_estimated_tokens": 585,
202
+ "max_estimated_tokens": 603,
203
203
  "steps": [
204
204
  {
205
205
  "id": "refuse-option",
206
- "max_estimated_tokens": 422,
207
- "accounting_mode": "independent_transport"
206
+ "max_estimated_tokens": 440,
207
+ "accounting_mode": "self_reported"
208
208
  },
209
209
  {
210
210
  "id": "retry-option",
@@ -261,5 +261,5 @@
261
261
  ]
262
262
  }
263
263
  ],
264
- "composite_max_estimated_tokens": 12477
264
+ "composite_max_estimated_tokens": 12667
265
265
  }
@@ -186,6 +186,7 @@
186
186
  "expected_accounting_mode": "self_reported",
187
187
  "required_fields": ["code", "refusal", "recovery"],
188
188
  "expected_error_code": "unknown_context_intent",
189
+ "expected_field_values": { "recovery.recovery_mode": "compact" },
189
190
  "expected_refusal_surface": "--for"
190
191
  },
191
192
  {
@@ -216,7 +217,7 @@
216
217
  ],
217
218
  "expected_exit_code": 2,
218
219
  "expected_output_kind": "refusal",
219
- "expected_accounting_mode": "independent_transport",
220
+ "expected_accounting_mode": "self_reported",
220
221
  "required_fields": ["code", "refusal", "recovery"],
221
222
  "expected_error_code": "unknown_option",
222
223
  "expected_refusal_surface": "--include-body"
@@ -0,0 +1,14 @@
1
+ # Public SDK Agent Environment
2
+
3
+ Tracker: [pm-t8a0x1](../../../.agents/pm/features/pm-t8a0x1.toon)
4
+
5
+ This executable example imports only Node.js built-ins and `@unbrained/pm-cli/sdk`. It creates an isolated temporary tracker, uses ordinary `PmClient` actions, serves a budgeted observation, evaluates recorded state, and closes the episode. It has no machine-learning dependencies.
6
+
7
+ From an installed package checkout:
8
+
9
+ ```bash
10
+ npm install @unbrained/pm-cli
11
+ npm start
12
+ ```
13
+
14
+ The JSON result is intentionally small and stable enough for a CI assertion. The temporary workspace is removed after the run.
@@ -0,0 +1,8 @@
1
+ {
2
+ "name": "pm-sdk-agent-environment-example",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "start": "node run-agent-environment.mjs"
7
+ }
8
+ }
@@ -0,0 +1,154 @@
1
+ import { mkdtemp, rm } from "node:fs/promises";
2
+ import { tmpdir } from "node:os";
3
+ import { join } from "node:path";
4
+ import {
5
+ PM_EPISODE_SCHEMA,
6
+ PM_OBSERVATION_SCHEMA,
7
+ PM_VERDICT_SCHEMA,
8
+ PM_WORKSPACE_RECIPE_SCHEMA,
9
+ PmClient,
10
+ defineEpisodeSpecification,
11
+ openPmEpisode,
12
+ runWithWorkspaceRecipe,
13
+ } from "@unbrained/pm-cli/sdk";
14
+
15
+ class PublicSdkAdapter {
16
+ constructor(workspace) {
17
+ this.client = new PmClient({ cwd: workspace, noExtensions: true });
18
+ this.itemId = "";
19
+ this.revision = 0;
20
+ }
21
+
22
+ async reset(recipe) {
23
+ const created = await runWithWorkspaceRecipe(recipe, async () => {
24
+ await this.client.init("environment");
25
+ return this.client.create({
26
+ id: "pm-created-by-adapter",
27
+ title: "Complete the SDK environment task",
28
+ type: "Task",
29
+ status: "open",
30
+ description: "Created inside a deterministic public-SDK episode.",
31
+ });
32
+ });
33
+ this.itemId = created.item.id;
34
+ this.revision = 0;
35
+ return { workspace_id: "temporary-pm-workspace", state_id: "revision:0" };
36
+ }
37
+
38
+ async execute(_action) {
39
+ const result = await this.client.close(
40
+ this.itemId,
41
+ "Public SDK episode completed",
42
+ {
43
+ resolution: "The ordinary PmClient close action recorded completion.",
44
+ expected: "The task is closed through the public SDK.",
45
+ actual: "The task is closed through the public SDK.",
46
+ validateClose: "warn",
47
+ },
48
+ );
49
+ this.revision += 1;
50
+ return { state_id: `revision:${this.revision}`, output: result };
51
+ }
52
+
53
+ async readRecordedState() {
54
+ const result = await this.client.get(this.itemId);
55
+ return {
56
+ snapshot_id: `revision:${this.revision}`,
57
+ state: {
58
+ item: {
59
+ id: result.item.id,
60
+ title: result.item.title,
61
+ status: result.item.status,
62
+ resolution: result.item.resolution,
63
+ },
64
+ },
65
+ };
66
+ }
67
+ }
68
+
69
+ const observation = {
70
+ schema: PM_OBSERVATION_SCHEMA,
71
+ id: "sdk-task-state",
72
+ version: 1,
73
+ reads: [{ command: "get", budget_tokens: 256 }],
74
+ calibration: {
75
+ basis: "emitted_bytes",
76
+ samples: [96, 128, 160],
77
+ expected_emitted_bytes: 128,
78
+ tolerance_bytes: 32,
79
+ },
80
+ corpus_dependence: { kind: "independent" },
81
+ tiers: [
82
+ {
83
+ id: "standard",
84
+ max_tokens: 256,
85
+ fields: ["item.id", "item.title", "item.status", "item.resolution"],
86
+ },
87
+ { id: "identity", max_tokens: 48, fields: ["item.id", "item.status"] },
88
+ ],
89
+ };
90
+
91
+ const verdict = {
92
+ schema: PM_VERDICT_SCHEMA,
93
+ id: "sdk-task-closed",
94
+ version: 1,
95
+ predicates: [
96
+ {
97
+ id: "closed",
98
+ kind: "field_equals",
99
+ path: "item.status",
100
+ expected: "closed",
101
+ },
102
+ { id: "explained", kind: "field_present", path: "item.resolution" },
103
+ ],
104
+ composition: { operator: "all", predicate_ids: ["closed", "explained"] },
105
+ };
106
+
107
+ const workspace = await mkdtemp(join(tmpdir(), "pm-sdk-environment-"));
108
+ try {
109
+ const session = await openPmEpisode(
110
+ defineEpisodeSpecification({
111
+ schema: PM_EPISODE_SCHEMA,
112
+ id: "public-sdk-environment",
113
+ version: 1,
114
+ mode: "evaluation",
115
+ recipe: {
116
+ schema: PM_WORKSPACE_RECIPE_SCHEMA,
117
+ seed: "public-sdk-environment",
118
+ clock: "2026-09-03T00:00:00.000Z",
119
+ tickMs: 1,
120
+ operations: [],
121
+ },
122
+ task_item_ids: ["pm-created-by-adapter"],
123
+ observable_fields: [
124
+ "item.id",
125
+ "item.title",
126
+ "item.status",
127
+ "item.resolution",
128
+ ],
129
+ withheld_fields: ["grading.expected_status"],
130
+ observation,
131
+ verdict,
132
+ limits: {
133
+ max_actions: 1,
134
+ max_observations: 2,
135
+ max_tokens_per_observation: 256,
136
+ },
137
+ }),
138
+ new PublicSdkAdapter(workspace),
139
+ );
140
+ const initial = await session.observe();
141
+ await session.step({ kind: "close" });
142
+ const completed = await session.close();
143
+ process.stdout.write(
144
+ `${JSON.stringify({
145
+ initial_status: initial.status,
146
+ initial_tier: initial.receipt.served_tier,
147
+ verdict: completed.verdict.outcome,
148
+ policy: completed.verdict.policy,
149
+ trajectory: completed.trajectory.map((entry) => entry.kind),
150
+ })}\n`,
151
+ );
152
+ } finally {
153
+ await rm(workspace, { recursive: true, force: true });
154
+ }
@@ -5,7 +5,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
5
5
  | Command | Capability family | Canonical flags | Maximum |
6
6
  | --- | --- | ---: | ---: |
7
7
  | `init` | workspace | 30 | 30 |
8
- | `config` | workspace | 35 | 35 |
8
+ | `config` | workspace | 36 | 36 |
9
9
  | `extension` | extensions | 53 | 53 |
10
10
  | `package` | extensions | 54 | 54 |
11
11
  | `packages` | extensions | 54 | 54 |
@@ -15,7 +15,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
15
15
  | `copy` | intake | 24 | 24 |
16
16
  | `focus` | intake | 22 | 22 |
17
17
  | `list` | context | 86 | 86 |
18
- | `list-all` | context | 85 | 85 |
18
+ | `list-all` | context | 86 | 86 |
19
19
  | `list-draft` | context | 84 | 84 |
20
20
  | `list-open` | context | 84 | 84 |
21
21
  | `list-in-progress` | context | 84 | 84 |
@@ -30,32 +30,32 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
30
30
  | `search` | context | 78 | 78 |
31
31
  | `duplicates` | context | 24 | 24 |
32
32
  | `eval` | context | 25 | 25 |
33
- | `next` | context | 35 | 35 |
33
+ | `next` | context | 38 | 38 |
34
34
  | `history` | evidence | 35 | 35 |
35
35
  | `events` | evidence | 33 | 33 |
36
36
  | `history-redact` | evidence | 27 | 27 |
37
- | `history-repair` | evidence | 26 | 26 |
37
+ | `history-repair` | evidence | 27 | 27 |
38
38
  | `history-compact` | evidence | 30 | 30 |
39
39
  | `history-author-acknowledge` | evidence | 28 | 28 |
40
- | `merge` | workspace | 24 | 24 |
40
+ | `merge` | workspace | 27 | 27 |
41
41
  | `schema` | workspace | 40 | 40 |
42
42
  | `profile` | workspace | 22 | 22 |
43
43
  | `activity` | context | 35 | 35 |
44
44
  | `restore` | intake | 23 | 23 |
45
45
  | `update` | lifecycle | 105 | 105 |
46
- | `update-many` | lifecycle | 140 | 140 |
46
+ | `update-many` | lifecycle | 146 | 146 |
47
47
  | `close` | lifecycle | 31 | 31 |
48
48
  | `close-many` | lifecycle | 72 | 72 |
49
49
  | `delete` | lifecycle | 24 | 24 |
50
- | `append` | evidence | 24 | 24 |
50
+ | `append` | evidence | 25 | 25 |
51
51
  | `comments` | evidence | 31 | 31 |
52
52
  | `notes` | evidence | 35 | 35 |
53
- | `learnings` | evidence | 27 | 27 |
53
+ | `learnings` | evidence | 31 | 31 |
54
54
  | `files` | evidence | 39 | 39 |
55
55
  | `docs` | evidence | 30 | 30 |
56
56
  | `deps` | graph | 32 | 32 |
57
57
  | `plan` | graph | 109 | 109 |
58
- | `test` | quality | 52 | 52 |
58
+ | `test` | quality | 53 | 53 |
59
59
  | `test-all` | quality | 40 | 40 |
60
60
  | `telemetry` | workspace | 21 | 21 |
61
61
  | `stats` | context | 29 | 29 |
@@ -65,7 +65,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
65
65
  | `gc` | workspace | 22 | 22 |
66
66
  | `workspace` | workspace | 23 | 23 |
67
67
  | `contracts` | quality | 29 | 29 |
68
- | `claim` | lifecycle | 36 | 36 |
68
+ | `claim` | lifecycle | 38 | 38 |
69
69
  | `release` | lifecycle | 23 | 23 |
70
70
  | `start-task` | lifecycle | 23 | 23 |
71
71
  | `pause-task` | lifecycle | 23 | 23 |
@@ -4,12 +4,12 @@ Tracker: `pm-f05lsg`.
4
4
 
5
5
  Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
6
6
 
7
- - Catalog error codes: 356
7
+ - Catalog error codes: 365
8
8
  - Executable error codes: 19
9
9
  - Executable-code ratchet floor: 18
10
10
  - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
11
- - Uncovered error codes: 337
12
- - Coverage fraction: 0.053371
11
+ - Uncovered error codes: 346
12
+ - Coverage fraction: 0.052055
13
13
  - Closed-domain probes: 19
14
14
  - Grammar probes: 94
15
15
 
@@ -111,17 +111,23 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
111
111
  | `history_author_acknowledge_selector_required` | `history_author_acknowledge_selector_required` | uncovered | none | 0 |
112
112
  | `history_author_acknowledge_target_not_actionable` | `history_author_acknowledge_target_not_actionable` | uncovered | none | 0 |
113
113
  | `history_author_acknowledge_target_unreadable` | `history_author_acknowledge_target_unreadable` | uncovered | none | 0 |
114
+ | `history_baseline_unavailable` | `history_baseline_unavailable` | uncovered | none | 0 |
114
115
  | `history_drift_chain_mismatch` | `history_drift_chain_mismatch` | uncovered | none | 0 |
115
116
  | `history_drift_hash_mismatch` | `history_drift_hash_mismatch` | uncovered | none | 0 |
116
117
  | `history_drift_merge_receipt` | `history_drift_merge_receipt` | uncovered | none | 0 |
117
118
  | `history_drift_missing_stream` | `history_drift_missing_stream` | uncovered | none | 0 |
118
119
  | `history_drift_unreadable_stream` | `history_drift_unreadable_stream` | uncovered | none | 0 |
119
120
  | `history_drift_version_skew` | `history_drift_version_skew` | uncovered | none | 0 |
121
+ | `history_json_invalid` | `history_json_invalid` | uncovered | none | 0 |
120
122
  | `history_merge_conflict_markers_detected` | `merge_conflict_markers_detected` | uncovered | none | 0 |
123
+ | `history_replay_invalid` | `history_replay_invalid` | uncovered | none | 0 |
124
+ | `history_salvage_refused` | `history_salvage_refused` | uncovered | none | 0 |
121
125
  | `history_stream_over_compact_threshold` | `history_stream_over_compact_threshold` | uncovered | none | 0 |
122
126
  | `history_target_out_of_range` | `history_target_out_of_range` | uncovered | none | 0 |
123
127
  | `history_timestamp_invalid` | `history_timestamp_invalid` | uncovered | none | 0 |
124
128
  | `history_unknown_author_events` | `history_unknown_author_events` | uncovered | none | 0 |
129
+ | `history_version_mapping_unavailable` | `history_version_mapping_unavailable` | uncovered | none | 0 |
130
+ | `history_version_pruned` | `history_version_pruned` | uncovered | none | 0 |
125
131
  | `host_environment_capacity_fault` | `host_environment_capacity_fault` | uncovered | none | 0 |
126
132
  | `host_environment_operation_invalid` | `host_environment_operation_invalid` | uncovered | none | 0 |
127
133
  | `host_environment_permission_fault` | `host_environment_permission_fault` | uncovered | none | 0 |
@@ -163,9 +169,11 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
163
169
  | `invalid_reproducible_process_environment` | `invalid_reproducible_process_environment` | uncovered | none | 0 |
164
170
  | `invalid_workspace_snapshot_target` | `invalid_workspace_snapshot_target` | uncovered | none | 0 |
165
171
  | `item_already_active` | `item_already_active` | uncovered | none | 0 |
172
+ | `item_document_encoding_invalid` | `item_document_encoding_invalid` | uncovered | none | 0 |
166
173
  | `item_document_invalid` | `item_document_invalid` | uncovered | none | 0 |
167
174
  | `item_document_roundtrip_failed` | `item_document_roundtrip_failed` | uncovered | none | 0 |
168
175
  | `item_id_collision` | `item_id_collision` | uncovered | none | 0 |
176
+ | `item_identity_reserved` | `item_identity_reserved` | uncovered | none | 0 |
169
177
  | `item_not_found` | `item_not_found` | uncovered | none | 0 |
170
178
  | `likely_duplicate` | `likely_duplicate` | uncovered | none | 0 |
171
179
  | `linked_artifact_mutation_conflict` | `linked_artifact_mutation_conflict` | uncovered | none | 0 |
@@ -233,6 +241,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
233
241
  | `profile_name_not_normalized` | `profile_name_not_normalized` | uncovered | none | 0 |
234
242
  | `profile_summary_empty` | `profile_summary_empty` | uncovered | none | 0 |
235
243
  | `profile_title_empty` | `profile_title_empty` | uncovered | none | 0 |
244
+ | `project_runtime_history_epoch_incompatible` | `project_runtime_history_epoch_incompatible` | uncovered | none | 0 |
236
245
  | `project_runtime_stale_mutation` | `project_runtime_stale_mutation` | uncovered | none | 0 |
237
246
  | `project_runtime_stale_read` | `project_runtime_stale_read` | uncovered | none | 0 |
238
247
  | `projection_options_mutually_exclusive` | `projection_options_mutually_exclusive` | executable | closed_domain | 3 |
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.9.3"
9
+ "version": "2026.9.5"
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.9.3",
16
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
4
4
  "description": "Git-native project management CLI for humans and agents.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@11.10.0",
@@ -76,7 +76,7 @@
76
76
  "import": "./dist/cli-bundle/sdk-testing.js",
77
77
  "default": "./dist/cli-bundle/sdk-testing.js"
78
78
  },
79
- "./sdk/public-surface.json": "./sdk/public-surface.json",
79
+ "./sdk/public-surface.json": "./dist/sdk/public-surface.json",
80
80
  "./cli": {
81
81
  "types": "./dist/cli/public.d.ts",
82
82
  "import": "./dist/cli/public.js",
@@ -95,7 +95,6 @@
95
95
  "LICENSE",
96
96
  "AGENTS.md",
97
97
  "docs/**",
98
- "sdk/public-surface.json",
99
98
  ".claude-plugin/**",
100
99
  "plugins/**",
101
100
  "packages/pm-*/**",
@@ -221,7 +220,7 @@
221
220
  "@eslint/js": "^10.0.1",
222
221
  "@modelcontextprotocol/ext-apps": "1.7.5",
223
222
  "@sentry/cli": "^3.7.0",
224
- "@types/node": "^26.4.0",
223
+ "@types/node": "^26.4.1",
225
224
  "@types/npm-package-arg": "^6.1.4",
226
225
  "@vitest/coverage-v8": "^4.1.11",
227
226
  "esbuild": "0.28.2",
@@ -229,8 +228,8 @@
229
228
  "eslint-plugin-sonarjs": "^4.2.0",
230
229
  "eslint-plugin-unicorn": "74.0.0",
231
230
  "fast-check": "^4.9.0",
232
- "greptile": "^3.4.2",
233
- "jscpd": "^5.1.1",
231
+ "greptile": "^3.5.0",
232
+ "jscpd": "^5.1.2",
234
233
  "tsx": "^4.23.13",
235
234
  "typescript": "^6.0.3",
236
235
  "typescript-eslint": "^8.69.0",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-beads",
3
- "version": "2026.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
3
+ "version": "2026.9.5",
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.9.3",
4
+ "version": "2026.9.5",
5
5
  "author": {
6
6
  "name": "unbrained",
7
7
  "url": "https://github.com/unbraind/pm-cli"
@@ -94,8 +94,8 @@ Load the smallest thing that answers the question. Costs are measured.
94
94
  | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
95
95
  | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
96
96
 
97
- Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
98
- `skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
97
+ Guide topics are declared at runtime: `pm guide` prints the current index and
98
+ `pm guide <topic> --depth brief` expands one topic. Do not copy the list.
99
99
 
100
100
  Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
101
101