@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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +35 -0
- package/dist/cli/main.js +4 -3
- package/dist/cli/register-annotations.d.ts +11 -0
- package/dist/cli/register-annotations.js +195 -0
- package/dist/cli/register-history-author.js +7 -30
- package/dist/cli/register-mutation.js +25 -206
- package/dist/cli/runtime-compatibility-boundary.d.ts +17 -0
- package/dist/cli/runtime-compatibility-boundary.js +43 -0
- package/dist/cli-bundle/bundle-manifest.json +155 -691
- package/dist/cli-bundle/chunks/chunk-2ZMXX3Q6.js +2068 -0
- package/dist/cli-bundle/chunks/chunk-ALDHXLPS.js +3 -0
- package/dist/cli-bundle/chunks/chunk-CBLA33YK.js +8 -0
- package/dist/cli-bundle/chunks/chunk-GKA54IJM.js +5 -0
- package/dist/cli-bundle/chunks/chunk-KRY7SRUO.js +2 -0
- package/dist/cli-bundle/chunks/chunk-MNJ4NNSY.js +26 -0
- package/dist/cli-bundle/chunks/chunk-NUXRRNAB.js +77 -0
- package/dist/cli-bundle/chunks/chunk-OJPCFDDY.js +13 -0
- package/dist/cli-bundle/chunks/chunk-PFSD3DAN.js +194 -0
- package/dist/cli-bundle/chunks/chunk-QWRRFYK3.js +2 -0
- package/dist/cli-bundle/chunks/chunk-SQ7QZFQ6.js +2 -0
- package/dist/cli-bundle/chunks/{register-list-query-FJZCJ67O.js → register-list-query-WFZAMJHZ.js} +8 -8
- package/dist/cli-bundle/chunks/register-mutation-SOKKOTHQ.js +20 -0
- package/dist/cli-bundle/chunks/register-operations-5XQETS6E.js +2 -0
- package/dist/cli-bundle/chunks/register-setup-2HL5ZHMK.js +2 -0
- package/dist/cli-bundle/focused-chunks/chunk-54EU2UVO.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-VZFU2R4M.js → chunk-5FLBTZJQ.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-5GJ57YKN.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-HNL6IFGS.js → chunk-ANTMGYLI.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-CMDS3KYT.js +14 -0
- package/dist/cli-bundle/focused-chunks/{chunk-NBJKQP4S.js → chunk-DMKOMTTY.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-CIXVQPB7.js → chunk-F5B3HBEZ.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-R2LEMEV5.js → chunk-FI6DWU2M.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-3K4XV2BF.js → chunk-FNOKJG6N.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-RW5IYD4J.js → chunk-FPDYXZBK.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-QHRTT7WT.js → chunk-GWI6YIKJ.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-MHMTKV5V.js → chunk-HCUC62AB.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-MOTJFQ3F.js → chunk-HGNKPSCB.js} +12 -12
- package/dist/cli-bundle/focused-chunks/{chunk-4VJQTS3P.js → chunk-IAS7PMLG.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-TIKDBG4D.js → chunk-PL2EYDJK.js} +27 -27
- package/dist/cli-bundle/focused-chunks/chunk-SM2PJGP3.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-RPNYG5MO.js → chunk-TCSAPH33.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-U646T7Z6.js +18 -0
- package/dist/cli-bundle/focused-chunks/chunk-YKPE4PPY.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-YZEZAPJK.js → chunk-YSAHYUXX.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-73JUDYXT.js → chunk-ZOLDTUU7.js} +2 -2
- package/dist/cli-bundle/main.js +13 -13
- package/dist/cli-bundle/sdk-authoring.js +1 -1
- package/dist/cli-bundle/sdk-contracts.js +1 -1
- package/dist/cli-bundle/sdk-core.js +38 -38
- package/dist/cli-bundle/sdk-governance.js +1 -1
- package/dist/cli-bundle/sdk-graph.js +1 -1
- package/dist/cli-bundle/sdk-merge.js +1 -1
- package/dist/cli-bundle/sdk-query.js +1 -1
- package/dist/cli-bundle/sdk-runtime.js +1 -1
- package/dist/cli-bundle/sdk-testing.js +1 -1
- package/dist/cli-bundle/sdk.js +2 -1
- package/dist/cli.js +14 -4
- package/dist/core/output/output.js +9 -2
- package/dist/core/sentry/helpers.d.ts +10 -0
- package/dist/core/sentry/helpers.js +59 -4
- package/dist/core/shared/constants.d.ts +2 -0
- package/dist/core/shared/constants.js +4 -2
- package/dist/sdk/annotations.d.ts +40 -0
- package/dist/sdk/annotations.js +61 -9
- package/dist/sdk/author-attribution.d.ts +12 -0
- package/dist/sdk/author-attribution.js +73 -11
- package/dist/sdk/cli-contracts/command-exit-contracts.d.ts +118 -0
- package/dist/sdk/cli-contracts/command-exit-contracts.js +152 -0
- package/dist/sdk/cli-contracts/completeness.js +5 -3
- package/dist/sdk/cli-contracts/flag-contracts.js +5 -2
- package/dist/sdk/cli-contracts/runtime-contracts.d.ts +11 -0
- package/dist/sdk/cli-contracts/runtime-contracts.js +29 -2
- package/dist/sdk/cli-contracts/tool-parameter-tables.js +15 -2
- package/dist/sdk/cli-contracts/tool-schema.d.ts +1 -1
- package/dist/sdk/cli-contracts/tool-schema.js +6 -3
- package/dist/sdk/comments.d.ts +7 -0
- package/dist/sdk/comments.js +2 -2
- package/dist/sdk/completion.js +9 -5
- package/dist/sdk/contracts.d.ts +1 -0
- package/dist/sdk/contracts.js +3 -2
- package/dist/sdk/environment/host-environment-errors.d.ts +27 -0
- package/dist/sdk/environment/host-environment-errors.js +124 -0
- package/dist/sdk/environment/project-runtime-compatibility.d.ts +65 -0
- package/dist/sdk/environment/project-runtime-compatibility.js +385 -0
- package/dist/sdk/environment/source-context.d.ts +23 -0
- package/dist/sdk/environment/source-context.js +29 -0
- package/dist/sdk/error-code-catalog.d.ts +6 -0
- package/dist/sdk/error-code-catalog.js +62 -8
- package/dist/sdk/generated-error-code-catalog.js +629 -3
- package/dist/sdk/governance/health.d.ts +11 -3
- package/dist/sdk/governance/health.js +5 -5
- package/dist/sdk/index.d.ts +7 -3
- package/dist/sdk/index.js +9 -5
- package/dist/sdk/learnings.d.ts +15 -0
- package/dist/sdk/learnings.js +2 -2
- package/dist/sdk/lifecycle/close-many.d.ts +6 -1
- package/dist/sdk/lifecycle/close-many.js +43 -5
- package/dist/sdk/lifecycle/update-many.d.ts +2 -1
- package/dist/sdk/lifecycle/update-many.js +29 -5
- package/dist/sdk/merge/index.d.ts +1 -1
- package/dist/sdk/merge/index.js +3 -3
- package/dist/sdk/merge/install.d.ts +21 -0
- package/dist/sdk/merge/install.js +50 -20
- package/dist/sdk/notes.d.ts +7 -0
- package/dist/sdk/notes.js +2 -2
- package/dist/sdk/read-output-contracts.js +83 -4
- package/dist/sdk/runtime.d.ts +1 -1
- package/dist/sdk/runtime.js +9 -25
- package/dist/sdk/test/execution.js +4 -2
- package/dist/sdk/test/parsers.js +5 -2
- package/dist/sdk/workspace-snapshot.d.ts +9 -0
- package/dist/sdk/workspace-snapshot.js +48 -16
- package/docs/AGENT_RUNTIME_PRIMITIVES.md +11 -4
- package/docs/README.md +1 -0
- package/docs/RELEASING.md +27 -2
- package/docs/SCRIPTING.md +27 -1
- package/docs/SDK_CONTEXT_INTEGRITY.md +66 -0
- package/docs/SDK_RUNTIME_BOUNDARIES.md +58 -0
- package/docs/SELF_DESCRIBING_CONTEXT_CONTRACTS.md +13 -0
- package/docs/TESTING.md +17 -0
- package/marketplace.json +2 -2
- package/package.json +5 -3
- package/packages/pm-beads/package.json +1 -1
- package/packages/pm-calendar/package.json +1 -1
- package/packages/pm-command-kit/package.json +1 -1
- package/packages/pm-digital-twin/package.json +1 -1
- package/packages/pm-governance-audit/package.json +1 -1
- package/packages/pm-guide-shell/package.json +1 -1
- package/packages/pm-kanban/package.json +1 -1
- package/packages/pm-lifecycle-hooks/package.json +1 -1
- package/packages/pm-linked-test-adapters/package.json +1 -1
- package/packages/pm-search-advanced/package.json +1 -1
- package/packages/pm-templates/package.json +1 -1
- package/packages/pm-todos/package.json +1 -1
- package/packages/pm-vcs/package.json +1 -1
- package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
- package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
- package/sdk/public-surface.json +529 -34
- package/dist/cli-bundle/chunks/append-7BXBFDGD.js +0 -2
- package/dist/cli-bundle/chunks/chunk-2AXF3VSK.js +0 -2
- package/dist/cli-bundle/chunks/chunk-2XS43CCV.js +0 -2
- package/dist/cli-bundle/chunks/chunk-3A6KWB72.js +0 -8
- package/dist/cli-bundle/chunks/chunk-3ISTDB42.js +0 -8
- package/dist/cli-bundle/chunks/chunk-4MTI7XOV.js +0 -5
- package/dist/cli-bundle/chunks/chunk-6BX5UDCN.js +0 -3
- package/dist/cli-bundle/chunks/chunk-6QPO7KLR.js +0 -2
- package/dist/cli-bundle/chunks/chunk-7MXHZHSQ.js +0 -5
- package/dist/cli-bundle/chunks/chunk-7ZPMJW4U.js +0 -2
- package/dist/cli-bundle/chunks/chunk-A6KGKEWT.js +0 -2
- package/dist/cli-bundle/chunks/chunk-AGYNSNCI.js +0 -2
- package/dist/cli-bundle/chunks/chunk-B4H7FEFH.js +0 -5
- package/dist/cli-bundle/chunks/chunk-B4KLBBMN.js +0 -2
- package/dist/cli-bundle/chunks/chunk-BXCSXK4J.js +0 -2
- package/dist/cli-bundle/chunks/chunk-CALJHNBL.js +0 -23
- package/dist/cli-bundle/chunks/chunk-CFIGP5LY.js +0 -2
- package/dist/cli-bundle/chunks/chunk-CHOQ2VAW.js +0 -2
- package/dist/cli-bundle/chunks/chunk-CS6MRHG7.js +0 -2
- package/dist/cli-bundle/chunks/chunk-CUGNQQKH.js +0 -2
- package/dist/cli-bundle/chunks/chunk-D4FPS43D.js +0 -164
- package/dist/cli-bundle/chunks/chunk-E2ZSLTOP.js +0 -2
- package/dist/cli-bundle/chunks/chunk-FB7G2HY2.js +0 -2
- package/dist/cli-bundle/chunks/chunk-H5Y5YE6A.js +0 -2
- package/dist/cli-bundle/chunks/chunk-H5Y6UV6E.js +0 -2
- package/dist/cli-bundle/chunks/chunk-H7KGWPDF.js +0 -2
- package/dist/cli-bundle/chunks/chunk-HFSD77TQ.js +0 -2
- package/dist/cli-bundle/chunks/chunk-HX2GTA6L.js +0 -2
- package/dist/cli-bundle/chunks/chunk-J2IEKAVR.js +0 -2
- package/dist/cli-bundle/chunks/chunk-JC6FKIFM.js +0 -2
- package/dist/cli-bundle/chunks/chunk-K44PYFXH.js +0 -2
- package/dist/cli-bundle/chunks/chunk-K4KGEEBT.js +0 -2
- package/dist/cli-bundle/chunks/chunk-KFLK5TRH.js +0 -21
- package/dist/cli-bundle/chunks/chunk-KL6IEBV2.js +0 -2
- package/dist/cli-bundle/chunks/chunk-KWQZDZSS.js +0 -2
- package/dist/cli-bundle/chunks/chunk-KZ4X3DGU.js +0 -3
- package/dist/cli-bundle/chunks/chunk-LD77HJMQ.js +0 -13
- package/dist/cli-bundle/chunks/chunk-LEPJJ6QC.js +0 -2
- package/dist/cli-bundle/chunks/chunk-ME2JJ4LA.js +0 -3
- package/dist/cli-bundle/chunks/chunk-NE5VRDAI.js +0 -2
- package/dist/cli-bundle/chunks/chunk-NFLJ3FHD.js +0 -2
- package/dist/cli-bundle/chunks/chunk-NG6OXIBR.js +0 -19
- package/dist/cli-bundle/chunks/chunk-NYIGHWQY.js +0 -8
- package/dist/cli-bundle/chunks/chunk-NZ75GNSA.js +0 -2
- package/dist/cli-bundle/chunks/chunk-PCJWJNC2.js +0 -2
- package/dist/cli-bundle/chunks/chunk-PD3225AM.js +0 -2
- package/dist/cli-bundle/chunks/chunk-PDEGKG7P.js +0 -2
- package/dist/cli-bundle/chunks/chunk-PIE5HBNA.js +0 -2
- package/dist/cli-bundle/chunks/chunk-PW2H7YJR.js +0 -56
- package/dist/cli-bundle/chunks/chunk-RSIC5OPE.js +0 -2
- package/dist/cli-bundle/chunks/chunk-TPKN3S7S.js +0 -2
- package/dist/cli-bundle/chunks/chunk-TPXAXTCO.js +0 -2
- package/dist/cli-bundle/chunks/chunk-UFWUJO4V.js +0 -2
- package/dist/cli-bundle/chunks/chunk-UQLZQVFW.js +0 -55
- package/dist/cli-bundle/chunks/chunk-VT3Z5G7D.js +0 -2
- package/dist/cli-bundle/chunks/chunk-WOD3WWUN.js +0 -2
- package/dist/cli-bundle/chunks/chunk-WSJEIGJF.js +0 -3
- package/dist/cli-bundle/chunks/chunk-WYNUU7ZW.js +0 -2008
- package/dist/cli-bundle/chunks/chunk-YGPNCCXZ.js +0 -2
- package/dist/cli-bundle/chunks/close-CMY3BAUG.js +0 -2
- package/dist/cli-bundle/chunks/close-many-SA4XZCTK.js +0 -2
- package/dist/cli-bundle/chunks/comments-EZ556ZD3.js +0 -2
- package/dist/cli-bundle/chunks/copy-ZSGPA52X.js +0 -2
- package/dist/cli-bundle/chunks/create-I5DVV4YG.js +0 -2
- package/dist/cli-bundle/chunks/delete-RL3JACSW.js +0 -2
- package/dist/cli-bundle/chunks/deps-S7UBCECS.js +0 -2
- package/dist/cli-bundle/chunks/docs-ZZNVBBYO.js +0 -2
- package/dist/cli-bundle/chunks/files-27C337VT.js +0 -2
- package/dist/cli-bundle/chunks/focus-5Z2SG7LU.js +0 -2
- package/dist/cli-bundle/chunks/history-compact-HJQK67CZ.js +0 -2
- package/dist/cli-bundle/chunks/history-redact-PWC6PDWA.js +0 -2
- package/dist/cli-bundle/chunks/history-repair-N3CY4WBF.js +0 -2
- package/dist/cli-bundle/chunks/learnings-4FH23XDT.js +0 -2
- package/dist/cli-bundle/chunks/profile-5Y5XXH5N.js +0 -2
- package/dist/cli-bundle/chunks/register-mutation-YGYPW3BL.js +0 -20
- package/dist/cli-bundle/chunks/register-operations-WMDSUMQF.js +0 -2
- package/dist/cli-bundle/chunks/register-setup-DL7FFABC.js +0 -2
- package/dist/cli-bundle/chunks/restore-6KYBV5BY.js +0 -2
- package/dist/cli-bundle/chunks/schema-EQGKBYXJ.js +0 -2
- package/dist/cli-bundle/chunks/update-QVTYOD6I.js +0 -2
- package/dist/cli-bundle/chunks/update-many-DJSBU525.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-2ECLECMK.js +0 -12
- package/dist/cli-bundle/focused-chunks/chunk-4EX25PXM.js +0 -8
- package/dist/cli-bundle/focused-chunks/chunk-DLTS3IHM.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-DQ6FKGL3.js +0 -14
- package/dist/cli-bundle/focused-chunks/chunk-JLG2C4EQ.js +0 -2
- 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,
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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-digital-twin",
|
|
3
|
-
"version": "2026.8.
|
|
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,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.
|
|
4
|
+
"version": "2026.8.8",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "unbrained",
|
|
7
7
|
"url": "https://github.com/unbraind/pm-cli"
|