@unbrained/pm-cli 2026.8.30 → 2026.9.1

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 (176) hide show
  1. package/.agents/skills/HARNESS_COMPATIBILITY.md +1 -1
  2. package/.agents/skills/README.md +1 -1
  3. package/.agents/skills/pm-developer/SKILL.md +1 -1
  4. package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md +2 -2
  5. package/.agents/skills/pm-developer/references/MULTI_AGENT_MERGE.md +1 -1
  6. package/.agents/skills/pm-developer/references/TOKEN_BUDGETS.md +1 -1
  7. package/.agents/skills/pm-extensions/SKILL.md +2 -2
  8. package/.agents/skills/pm-extensions/references/AUTHORING.md +1 -1
  9. package/.agents/skills/pm-extensions/references/LIFECYCLE.md +1 -1
  10. package/.agents/skills/pm-sdk/SKILL.md +1 -1
  11. package/.agents/skills/pm-user/SKILL.md +2 -2
  12. package/.agents/skills/pm-user/references/WORKFLOWS.md +2 -2
  13. package/.claude-plugin/marketplace.json +2 -2
  14. package/AGENTS.md +16 -14
  15. package/CHANGELOG.md +41 -6
  16. package/README.md +3 -3
  17. package/dist/cli/commands/merge.d.ts +1 -1
  18. package/dist/cli/commands/merge.js +3 -3
  19. package/dist/cli/register-list-query.js +32 -17
  20. package/dist/cli/register-mutation.js +8 -5
  21. package/dist/cli/register-operations.d.ts +2 -0
  22. package/dist/cli/register-operations.js +20 -9
  23. package/dist/cli-bundle/bundle-manifest.json +144 -144
  24. package/dist/cli-bundle/chunks/{chunk-CMIEDWAY.js → chunk-2MC2LCXZ.js} +41 -41
  25. package/dist/cli-bundle/chunks/{chunk-WS2GJQVG.js → chunk-3WICXLVT.js} +2 -2
  26. package/dist/cli-bundle/chunks/{chunk-7SKMLSMX.js → chunk-6XIIGE7U.js} +2 -2
  27. package/dist/cli-bundle/chunks/chunk-ALKKAUFN.js +35 -0
  28. package/dist/cli-bundle/chunks/{chunk-MTTKAUBX.js → chunk-DTGWEL23.js} +2 -2
  29. package/dist/cli-bundle/chunks/chunk-GOACULJW.js +13 -0
  30. package/dist/cli-bundle/chunks/chunk-NOPL37X4.js +205 -0
  31. package/dist/cli-bundle/chunks/{chunk-2UETTHY6.js → chunk-TAG4VC22.js} +30 -30
  32. package/dist/cli-bundle/chunks/{chunk-3TEF3HM5.js → chunk-U45JXJCC.js} +2 -2
  33. package/dist/cli-bundle/chunks/{chunk-TGNAA66W.js → chunk-X4RCGLTX.js} +2 -2
  34. package/dist/cli-bundle/chunks/{chunk-2MKLQL2E.js → chunk-Y7VOMSZT.js} +2 -2
  35. package/dist/cli-bundle/chunks/{register-list-query-OMKJ5ONN.js → register-list-query-XYNX4ASQ.js} +11 -11
  36. package/dist/cli-bundle/chunks/register-mutation-2MVLRS3J.js +20 -0
  37. package/dist/cli-bundle/chunks/register-operations-WCIDXBU3.js +2 -0
  38. package/dist/cli-bundle/chunks/{register-setup-GLQ5SYV3.js → register-setup-KVNC5KPL.js} +2 -2
  39. package/dist/cli-bundle/focused-chunks/{chunk-HVQ22RC4.js → chunk-2FEZ5SKM.js} +2 -2
  40. package/dist/cli-bundle/focused-chunks/{chunk-Y3JJXRVK.js → chunk-4O4CJAR6.js} +5 -5
  41. package/dist/cli-bundle/focused-chunks/chunk-7VATS5QY.js +16 -0
  42. package/dist/cli-bundle/focused-chunks/{chunk-LYFWQMVC.js → chunk-BEVHCEWG.js} +2 -2
  43. package/dist/cli-bundle/focused-chunks/{chunk-TDK3OCX3.js → chunk-FWPLDEXF.js} +2 -2
  44. package/dist/cli-bundle/focused-chunks/chunk-JEFKLWMM.js +2 -0
  45. package/dist/cli-bundle/focused-chunks/{chunk-JZYPPMXF.js → chunk-KB5OFSFD.js} +2 -2
  46. package/dist/cli-bundle/focused-chunks/{chunk-73EDXGYE.js → chunk-MKHG3T76.js} +2 -2
  47. package/dist/cli-bundle/focused-chunks/{chunk-3AVAWVZA.js → chunk-PF3E6Q36.js} +2 -2
  48. package/dist/cli-bundle/focused-chunks/{chunk-AD6ULRAF.js → chunk-QDFJIRKN.js} +4 -4
  49. package/dist/cli-bundle/focused-chunks/{chunk-RKOKG43G.js → chunk-RMRCQPWU.js} +2 -2
  50. package/dist/cli-bundle/focused-chunks/{chunk-XXOWRJZ5.js → chunk-S4U5CN5Q.js} +2 -2
  51. package/dist/cli-bundle/focused-chunks/{chunk-THEPQMLX.js → chunk-SVXJYD6G.js} +2 -2
  52. package/dist/cli-bundle/focused-chunks/chunk-T2LXXSOD.js +158 -0
  53. package/dist/cli-bundle/focused-chunks/chunk-Y6JJIX6I.js +51 -0
  54. package/dist/cli-bundle/main.js +2 -2
  55. package/dist/cli-bundle/sdk-authoring.js +1 -1
  56. package/dist/cli-bundle/sdk-contracts.js +1 -1
  57. package/dist/cli-bundle/sdk-core.js +27 -27
  58. package/dist/cli-bundle/sdk-governance.js +1 -1
  59. package/dist/cli-bundle/sdk-graph.js +1 -1
  60. package/dist/cli-bundle/sdk-merge.js +33 -33
  61. package/dist/cli-bundle/sdk-query.js +1 -1
  62. package/dist/cli-bundle/sdk-runtime.js +1 -1
  63. package/dist/cli-bundle/sdk-testing.js +1 -1
  64. package/dist/cli-bundle/sdk.js +10 -10
  65. package/dist/core/history/drift-scan.js +6 -6
  66. package/dist/core/history/history.d.ts +6 -0
  67. package/dist/core/history/history.js +47 -5
  68. package/dist/core/history/replay.d.ts +12 -1
  69. package/dist/core/history/replay.js +60 -39
  70. package/dist/core/schema/runtime-schema.d.ts +4 -0
  71. package/dist/core/schema/runtime-schema.js +60 -48
  72. package/dist/core/schema/status-defs-file.js +5 -2
  73. package/dist/mcp/legacy-adapter.d.ts +11 -2
  74. package/dist/mcp/legacy-adapter.js +26 -12
  75. package/dist/mcp/server.d.ts +2 -2
  76. package/dist/mcp/server.js +78 -15
  77. package/dist/mcp/tool-definitions.js +56 -2
  78. package/dist/sdk/agent-capability-contracts.js +4 -2
  79. package/dist/sdk/cli-contracts/flag-contracts.d.ts +2 -0
  80. package/dist/sdk/cli-contracts/flag-contracts.js +6 -2
  81. package/dist/sdk/cli-contracts/grammar-contracts.d.ts +1 -1
  82. package/dist/sdk/cli-contracts/grammar-contracts.js +12 -2
  83. package/dist/sdk/cli-contracts/runtime-contracts.js +3 -2
  84. package/dist/sdk/cli-contracts/tool-schema.js +11 -3
  85. package/dist/sdk/generated/generated-error-code-catalog-part-2.js +14 -2
  86. package/dist/sdk/governance/health.js +17 -6
  87. package/dist/sdk/governance/status-role-diagnostics.d.ts +27 -0
  88. package/dist/sdk/governance/status-role-diagnostics.js +36 -0
  89. package/dist/sdk/governance/validate-normalization.d.ts +6 -0
  90. package/dist/sdk/governance/validate-normalization.js +37 -0
  91. package/dist/sdk/governance/validate.d.ts +1 -1
  92. package/dist/sdk/governance/validate.js +20 -35
  93. package/dist/sdk/governance/workspace-position.d.ts +69 -0
  94. package/dist/sdk/governance/workspace-position.js +164 -0
  95. package/dist/sdk/governance.d.ts +2 -0
  96. package/dist/sdk/governance.js +4 -2
  97. package/dist/sdk/history-read.js +14 -6
  98. package/dist/sdk/history-repair.js +17 -10
  99. package/dist/sdk/index.d.ts +2 -1
  100. package/dist/sdk/index.js +4 -3
  101. package/dist/sdk/init-agent-guidance.js +4 -4
  102. package/dist/sdk/lifecycle/update.js +23 -10
  103. package/dist/sdk/mcp/discovery.d.ts +152 -0
  104. package/dist/sdk/mcp/discovery.js +495 -0
  105. package/dist/sdk/mcp/protocol.d.ts +10 -2
  106. package/dist/sdk/mcp/protocol.js +15 -4
  107. package/dist/sdk/merge/index.d.ts +1 -1
  108. package/dist/sdk/merge/index.js +3 -3
  109. package/dist/sdk/merge/receipts.d.ts +27 -1
  110. package/dist/sdk/merge/receipts.js +27 -8
  111. package/dist/sdk/merge/three-way.d.ts +3 -1
  112. package/dist/sdk/merge/three-way.js +9 -7
  113. package/dist/sdk/query/context.js +11 -14
  114. package/dist/sdk/query/list.d.ts +2 -0
  115. package/dist/sdk/query/list.js +33 -12
  116. package/dist/sdk/runtime-extended-actions.js +10 -6
  117. package/dist/sdk/schema.js +12 -2
  118. package/dist/sdk/test/execution.d.ts +15 -0
  119. package/dist/sdk/test/execution.js +35 -27
  120. package/docs/AGENT_GUIDE.md +12 -4
  121. package/docs/AGENT_PROVENANCE_ADR.md +1 -1
  122. package/docs/AGENT_RUNTIME_PRIMITIVES.md +2 -2
  123. package/docs/ARCHITECTURE.md +5 -0
  124. package/docs/CLAUDE_CODE_PLUGIN.md +5 -5
  125. package/docs/COMMANDS.md +12 -12
  126. package/docs/CONFIGURATION.md +1 -1
  127. package/docs/CONTEXT_RECOVERY_PRIMITIVES.md +14 -5
  128. package/docs/DEFECT_RECURRENCE.md +2 -0
  129. package/docs/MCP_2026_07_28.md +33 -9
  130. package/docs/MCP_2026_07_28_CONFORMANCE.md +1 -0
  131. package/docs/MCP_CAPABILITY_SURFACES.md +7 -1
  132. package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md +15 -3
  133. package/docs/MERGE_SAFETY.md +30 -2
  134. package/docs/ONBOARDING.md +1 -1
  135. package/docs/OUTPUT_TOKEN_ACCOUNTING.md +5 -3
  136. package/docs/PROGRESSIVE_TOOL_DISCOVERY.md +42 -0
  137. package/docs/README.md +3 -1
  138. package/docs/READ_OUTPUT_CONTRACTS.md +1 -1
  139. package/docs/RECURRENCE_RECOVERY_CONTRACTS.md +1 -1
  140. package/docs/SDK.md +3 -3
  141. package/docs/TESTING.md +23 -14
  142. package/docs/WORKSPACE_POSITION_AND_LIFECYCLE.md +113 -0
  143. package/docs/agent-task-token-baseline.json +157 -3
  144. package/docs/agent-task-transcripts.json +143 -0
  145. package/docs/examples/policy-restricted-extension/README.md +2 -2
  146. package/docs/examples/starter-extension/README.md +1 -1
  147. package/docs/generated/REFUSAL_CLOSURE_CENSUS.md +4 -3
  148. package/docs/performance/cli-transport-overhead.md +8 -6
  149. package/marketplace.json +2 -2
  150. package/package.json +4 -4
  151. package/packages/pm-beads/package.json +1 -1
  152. package/packages/pm-calendar/package.json +1 -1
  153. package/packages/pm-command-kit/package.json +1 -1
  154. package/packages/pm-digital-twin/package.json +1 -1
  155. package/packages/pm-governance-audit/package.json +1 -1
  156. package/packages/pm-guide-shell/package.json +1 -1
  157. package/packages/pm-kanban/package.json +1 -1
  158. package/packages/pm-lifecycle-hooks/package.json +1 -1
  159. package/packages/pm-linked-test-adapters/package.json +1 -1
  160. package/packages/pm-search-advanced/package.json +1 -1
  161. package/packages/pm-templates/package.json +1 -1
  162. package/packages/pm-todos/package.json +1 -1
  163. package/packages/pm-vcs/package.json +1 -1
  164. package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
  165. package/plugins/pm-claude/README.md +4 -3
  166. package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
  167. package/sdk/public-surface.json +314 -10
  168. package/dist/cli-bundle/chunks/chunk-7X6OZEIV.js +0 -34
  169. package/dist/cli-bundle/chunks/chunk-GNWPTEBW.js +0 -205
  170. package/dist/cli-bundle/chunks/chunk-N6OR6FAR.js +0 -13
  171. package/dist/cli-bundle/chunks/register-mutation-QBSNCOY3.js +0 -20
  172. package/dist/cli-bundle/chunks/register-operations-UC77FQZC.js +0 -2
  173. package/dist/cli-bundle/focused-chunks/chunk-3UMBF26I.js +0 -158
  174. package/dist/cli-bundle/focused-chunks/chunk-AXZ5AJAF.js +0 -50
  175. package/dist/cli-bundle/focused-chunks/chunk-G6PATS5E.js +0 -16
  176. package/dist/cli-bundle/focused-chunks/chunk-LLNTHF5X.js +0 -2
package/docs/TESTING.md CHANGED
@@ -8,10 +8,11 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
8
8
 
9
9
  - Unit and integration tests must not read or write real `.agents/pm` data.
10
10
  - Prefer `node scripts/run-tests.mjs ...` because it creates sandboxed `PM_PATH` and `PM_GLOBAL_PATH`.
11
- - Linked tests added through `pm test` should use sandbox-safe commands.
12
- Package-manager scripts such as `pnpm test` are allowed because linked-test
13
- execution injects isolated `PM_PATH` and `PM_GLOBAL_PATH`; direct runners such
14
- as `vitest` still need `node scripts/run-tests.mjs ...` or inline sandbox env.
11
+ - Linked-test execution injects isolated `PM_PATH` and `PM_GLOBAL_PATH` for
12
+ every command and applies stored-command provenance checks before process
13
+ creation. Direct runners are accepted; prefer
14
+ `node scripts/run-tests.mjs ...` when the repository provides it because the
15
+ wrapper also reproduces build, coverage, and cleanup policy.
15
16
  - Run linked tests before closing the item that owns the work.
16
17
 
17
18
  Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
@@ -62,7 +63,8 @@ and stable error-code drift across the aggregate and every narrow SDK
62
63
  entrypoint. The performance gates protect entrypoint import cost and one-item
63
64
  CLI cold-start overhead without touching the repository tracker.
64
65
 
65
- `pnpm lint` is the local CodeFactor parity check. It layers ESLint rules for
66
+ `pnpm lint` and `pnpm quality:static` are the same canonical local static gate.
67
+ The gate layers ESLint rules for
66
68
  shipped source, package, plugin, and script surfaces that match the CodeFactor
67
69
  maintainability findings this repo tracks (`complexity`,
68
70
  `no-unsafe-optional-chaining`, and the relevant `eslint-plugin-unicorn`
@@ -193,7 +195,7 @@ Fixture source:
193
195
  Local run:
194
196
 
195
197
  ```bash
196
- pm install search-advanced --project
198
+ pm package install search-advanced --project
197
199
  pm reindex --mode keyword --eval --eval-fixtures tests/search-eval/golden-queries.json --json
198
200
  ```
199
201
 
@@ -385,12 +387,12 @@ correction; executable retry argv is never collection-truncated. The
385
387
  missing-probe negative control and the authoritative tracker-state snapshot
386
388
  prove that the corpus cannot silently shrink or turn a refusal into a mutation.
387
389
 
388
- The gate derives every supported harness, model, session, and provenance
389
- environment key from the SDK-owned harness descriptor registry. It deletes
390
- those host inputs before each fixture invocation, then supplies only the
391
- fixture's deterministic author and isolated tracker settings. Unrelated host
392
- environment values remain available, so the test process stays representative
393
- without allowing the launching agent or CI harness to change measured output.
390
+ The gate starts every fixture command from a closed environment allowlist. It
391
+ retains only declared process-portability inputs such as `PATH`, temporary and
392
+ home roots, and Windows process-launch variables, then supplies fixed locale,
393
+ timezone, author, telemetry, and isolated tracker settings. Undeclared host
394
+ values cannot reach measured output, including future harness variables that
395
+ the descriptor registry does not yet know about.
394
396
 
395
397
  ## Linked Tests
396
398
 
@@ -493,6 +495,13 @@ trusted legacy command.
493
495
  These pre-execution refusals use the `trust_refusal` failure category, separate
494
496
  from command or assertion failures.
495
497
 
498
+ Command-string shape is intentionally not treated as a security boundary.
499
+ Direct `node --test`, Vitest, package-manager, shell-wrapped, and non-Node
500
+ runners are accepted consistently because the runtime injects tracker
501
+ isolation for all of them. `classifyLinkedTestCommandSafety` exposes the same
502
+ SDK policy to package hosts and returns advisory runner classification;
503
+ provenance review and acknowledgment remain the execution trust boundary.
504
+
496
505
  Choose one explicit recovery:
497
506
 
498
507
  ```bash
@@ -577,7 +586,7 @@ Linked tests can include assertion metadata:
577
586
 
578
587
  ```bash
579
588
  pm test <item-id> --add \
580
- command="pm list-open --json",timeout_seconds=120,assert_json_field_gte=count:0
589
+ command="pm list --status open --json",timeout_seconds=120,assert_json_field_gte=count:0
581
590
  ```
582
591
 
583
592
  Common assertion keys include:
@@ -614,7 +623,7 @@ exemplar for background run management. Install it in an isolated project when
614
623
  validating package-provided test-run surfaces:
615
624
 
616
625
  ```bash
617
- pm install linked-test-adapters --project
626
+ pm package install linked-test-adapters --project
618
627
  pm package doctor --project --detail deep --trace
619
628
  pm test-runs list --json
620
629
  ```
@@ -0,0 +1,113 @@
1
+ # Workspace Position and Lifecycle Roles
2
+
3
+ Tracker references: [pm-bq0ii8](../.agents/pm/features/pm-bq0ii8.toon), [pm-0mhspz](../.agents/pm/issues/pm-0mhspz.toon)
4
+
5
+ ## Agent Quick Context
6
+
7
+ Project management is context management. A project status must therefore be both semantically classifiable and operationally safe to merge. Two SDK-owned primitives provide that baseline:
8
+
9
+ - lifecycle roles make custom workflow states participate consistently in `next`, `context`, list aliases, validation, and health;
10
+ - workspace position combines merge-fence, pending merge-receipt, and append-only history evidence into one bounded readiness state and one next action.
11
+
12
+ ## Role-Safe Custom Statuses
13
+
14
+ Every newly registered custom status requires at least one lifecycle role:
15
+
16
+ ```bash
17
+ pm schema add-status review --role active
18
+ pm schema add-status waiting_external --role blocked
19
+ pm schema add-status abandoned --role terminal --role terminal_canceled
20
+ ```
21
+
22
+ The supported roles are `draft`, `active`, `blocked`, `terminal`, `terminal_done`, `terminal_canceled`, `default_open`, `default_close`, and `default_cancel`. A status may have multiple roles when it is both a lifecycle member and a workflow default.
23
+
24
+ An existing status can be updated without repeating `--role`; its registered role is preserved. New roleless statuses and explicit empty role lists are refused. This prevents an item from being accepted into storage but disappearing from every actionable read.
25
+
26
+ Role-derived behavior is shared:
27
+
28
+ - `pm next` treats every `active` status as actionable unless dependency or blocker rules exclude it.
29
+ - `pm list --status open` and the deprecated `pm list-open` alias include active statuses other than the configured `in_progress_status`.
30
+ - `pm list --status in_progress` and `pm list-in-progress` select the configured in-progress workflow anchor.
31
+ - `pm context` guarantees `summary.active_items = summary.open + summary.in_progress`; custom active statuses cannot disappear from that accounting.
32
+ - `pm list-blocked` continues to combine blocked-role status and unresolved dependency evidence.
33
+
34
+ Legacy hand-edited or older trackers may still contain roleless definitions. Both commands surface the same warning and bounded affected-item evidence:
35
+
36
+ ```bash
37
+ pm health --check-only --full --json
38
+ pm validate --check-lifecycle --json
39
+ ```
40
+
41
+ Look for `schema_status_missing_lifecycle_role:<count>` and
42
+ `lifecycle_status_roles`. Diagnostics retain `roleless_status_count` while
43
+ bounding both status and affected-item ID samples with explicit truncation
44
+ flags. Repair the schema by re-registering each status with its intended role
45
+ before making workflow decisions.
46
+
47
+ ## One Workspace Position Read
48
+
49
+ Run:
50
+
51
+ ```bash
52
+ pm workspace position
53
+ pm workspace position --json
54
+ ```
55
+
56
+ The read requires no feature flag or session state. It reports:
57
+
58
+ - whether the committed `.gitattributes` merge fence matches the project schema;
59
+ - whether this clone has all required field-aware Git driver definitions;
60
+ - pending merge decisions, lossless receipt count, and invalid evidence count;
61
+ - bounded append-only history-drift counts and affected item IDs;
62
+ - one deterministic `state` and one `next_action.command`.
63
+
64
+ The next action always pins the inspected tracker with `--pm-path` and uses the
65
+ SDK's platform-aware command renderer. Paths with spaces or shell-significant
66
+ characters are therefore copy-safe on both POSIX shells and Windows command
67
+ lines, while package consumers can reuse `renderPmCommand` for their own
68
+ tokenized recovery actions.
69
+
70
+ Recovery precedence is intentional:
71
+
72
+ | State | Next action | Why it comes first |
73
+ | ------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
74
+ | `merge_evidence_invalid` | `pm merge report` | Untrusted evidence must be inspected before it can drive repair. |
75
+ | `history_evidence_invalid` | `pm validate --check-history-drift --full` | Required history evidence could not be interpreted safely. |
76
+ | `merge_reconciliation_required` | `pm merge reconcile` | Pending scalar decisions can explain and settle merge-created divergence. |
77
+ | `history_repair_required` | `pm history-repair --all` | Remaining append-only drift needs an audited re-anchor. |
78
+ | `merge_fence_unprepared` | `pm merge install` | The committed fence or clone-local drivers are absent or drifted. |
79
+ | `ready` | none | All included readiness predicates passed. |
80
+
81
+ `pm health --strict-exit` also treats missing clone-local merge drivers as blocking. Default health remains advisory for never-installed drivers so ordinary diagnostics retain backward compatibility.
82
+
83
+ ## SDK and Generic Runtime
84
+
85
+ Package authors can use the same implementation as the CLI:
86
+
87
+ ```ts
88
+ import {
89
+ inspectStatusRoleAssignments,
90
+ readWorkspacePosition,
91
+ resolveRuntimeStatusRegistry,
92
+ } from "@unbrained/pm-cli/sdk";
93
+
94
+ const position = await readWorkspacePosition({ path: ".agents/pm" });
95
+ if (!position.ok) {
96
+ console.log(position.next_action.command);
97
+ }
98
+ ```
99
+
100
+ The generic SDK/MCP action is `workspace` with `subcommand: "position"`. Snapshot operations remain `subcommand: "snapshot"` plus `snapshotAction`. Presentation layers do not duplicate readiness or lifecycle classification logic.
101
+
102
+ ## Operational Sequence
103
+
104
+ On a fresh clone:
105
+
106
+ ```bash
107
+ npm install -g .
108
+ pm merge install
109
+ pm workspace position --json
110
+ pm health --strict-exit --full --json
111
+ ```
112
+
113
+ After a branch merge, run workspace position before claiming that the tracker is safe. Follow only its selected next action, rerun the read, and continue until `state` is `ready`. This keeps remediation evidence ordered, token-bounded, and reproducible.
@@ -1,11 +1,165 @@
1
1
  {
2
- "version": 3,
2
+ "version": 4,
3
3
  "transcript_version": 2,
4
- "transcript_digest": "sha256:2bf91406426d2a9e5de1da10ba67f7b8e9d4a4baa09eb488fe89ae3925c78f3f",
4
+ "transcript_digest": "sha256:4f9e96bb6ce12bbbeb2514e4bd5958d201c4e62e95083bcbebd749d1e48cc82d",
5
5
  "estimator": "ceil(utf8_bytes / 4)",
6
6
  "measurement_scope": "output_before_token_accounting",
7
7
  "published_with_release": true,
8
+ "orientation": {
9
+ "canonical_task_id": "orientation-context-intent",
10
+ "required_capabilities": [
11
+ "actionable_work",
12
+ "active_ownership",
13
+ "workspace_state"
14
+ ],
15
+ "measured_winner_tokens": 1055,
16
+ "protocols": [
17
+ {
18
+ "task_id": "orientation-context-intent",
19
+ "command_count": 1,
20
+ "estimated_tokens": 1055,
21
+ "capabilities": [
22
+ "actionable_work",
23
+ "active_ownership",
24
+ "workspace_state"
25
+ ],
26
+ "capability_evidence": {
27
+ "actionable_work": [
28
+ {
29
+ "step_id": "context",
30
+ "field_path": "hierarchy"
31
+ }
32
+ ],
33
+ "active_ownership": [
34
+ {
35
+ "step_id": "context",
36
+ "field_path": "activity"
37
+ }
38
+ ],
39
+ "workspace_state": [
40
+ {
41
+ "step_id": "context",
42
+ "field_path": "summary.active_items"
43
+ }
44
+ ]
45
+ }
46
+ },
47
+ {
48
+ "task_id": "orientation-operating-rules",
49
+ "command_count": 4,
50
+ "estimated_tokens": 2293,
51
+ "capabilities": [
52
+ "actionable_work",
53
+ "active_ownership",
54
+ "workspace_state"
55
+ ],
56
+ "capability_evidence": {
57
+ "actionable_work": [
58
+ {
59
+ "step_id": "open",
60
+ "field_path": "items"
61
+ }
62
+ ],
63
+ "active_ownership": [
64
+ {
65
+ "step_id": "in-progress",
66
+ "field_path": "items"
67
+ }
68
+ ],
69
+ "workspace_state": [
70
+ {
71
+ "step_id": "context",
72
+ "field_path": "summary.active_items"
73
+ }
74
+ ]
75
+ }
76
+ },
77
+ {
78
+ "task_id": "orientation-contracts-next",
79
+ "command_count": 2,
80
+ "estimated_tokens": 4798,
81
+ "capabilities": [
82
+ "actionable_work",
83
+ "active_ownership",
84
+ "workspace_state"
85
+ ],
86
+ "capability_evidence": {
87
+ "actionable_work": [
88
+ {
89
+ "step_id": "next",
90
+ "field_path": "recommended.id"
91
+ }
92
+ ],
93
+ "active_ownership": [
94
+ {
95
+ "step_id": "next",
96
+ "field_path": "held_by_others"
97
+ }
98
+ ],
99
+ "workspace_state": [
100
+ {
101
+ "step_id": "next",
102
+ "field_path": "summary.in_progress"
103
+ }
104
+ ]
105
+ }
106
+ }
107
+ ]
108
+ },
8
109
  "tasks": [
110
+ {
111
+ "id": "orientation-context-intent",
112
+ "max_estimated_tokens": 1055,
113
+ "steps": [
114
+ {
115
+ "id": "context",
116
+ "max_estimated_tokens": 1055,
117
+ "accounting_mode": "self_reported"
118
+ }
119
+ ]
120
+ },
121
+ {
122
+ "id": "orientation-contracts-next",
123
+ "max_estimated_tokens": 4798,
124
+ "steps": [
125
+ {
126
+ "id": "contracts",
127
+ "max_estimated_tokens": 4111,
128
+ "accounting_mode": "self_reported"
129
+ },
130
+ {
131
+ "id": "next",
132
+ "max_estimated_tokens": 687,
133
+ "accounting_mode": "self_reported"
134
+ }
135
+ ]
136
+ },
137
+ {
138
+ "id": "orientation-operating-rules",
139
+ "max_estimated_tokens": 2293,
140
+ "steps": [
141
+ {
142
+ "id": "context",
143
+ "max_estimated_tokens": 1055,
144
+ "accounting_mode": "self_reported"
145
+ },
146
+ {
147
+ "id": "search",
148
+ "max_estimated_tokens": 164,
149
+ "accounting_mode": "self_reported"
150
+ },
151
+ {
152
+ "id": "open",
153
+ "max_estimated_tokens": 878,
154
+ "accounting_mode": "self_reported"
155
+ },
156
+ {
157
+ "id": "in-progress",
158
+ "max_estimated_tokens": 196,
159
+ "accounting_mode": "self_reported"
160
+ }
161
+ ]
162
+ },
9
163
  {
10
164
  "id": "context-bootstrap",
11
165
  "max_estimated_tokens": 1978,
@@ -107,5 +261,5 @@
107
261
  ]
108
262
  }
109
263
  ],
110
- "composite_max_estimated_tokens": 4331
264
+ "composite_max_estimated_tokens": 12477
111
265
  }
@@ -1,6 +1,149 @@
1
1
  {
2
2
  "version": 2,
3
+ "orientation": {
4
+ "canonical_task_id": "orientation-context-intent",
5
+ "required_capabilities": [
6
+ "workspace_state",
7
+ "active_ownership",
8
+ "actionable_work"
9
+ ],
10
+ "protocols": [
11
+ {
12
+ "task_id": "orientation-context-intent",
13
+ "capabilities": [
14
+ "workspace_state",
15
+ "active_ownership",
16
+ "actionable_work"
17
+ ],
18
+ "capability_evidence": {
19
+ "workspace_state": [
20
+ { "step_id": "context", "field_path": "summary.active_items" }
21
+ ],
22
+ "active_ownership": [
23
+ { "step_id": "context", "field_path": "activity" }
24
+ ],
25
+ "actionable_work": [
26
+ { "step_id": "context", "field_path": "hierarchy" }
27
+ ]
28
+ }
29
+ },
30
+ {
31
+ "task_id": "orientation-contracts-next",
32
+ "capabilities": [
33
+ "workspace_state",
34
+ "active_ownership",
35
+ "actionable_work"
36
+ ],
37
+ "capability_evidence": {
38
+ "workspace_state": [
39
+ { "step_id": "next", "field_path": "summary.in_progress" }
40
+ ],
41
+ "active_ownership": [
42
+ { "step_id": "next", "field_path": "held_by_others" }
43
+ ],
44
+ "actionable_work": [
45
+ { "step_id": "next", "field_path": "recommended.id" }
46
+ ]
47
+ }
48
+ },
49
+ {
50
+ "task_id": "orientation-operating-rules",
51
+ "capabilities": [
52
+ "workspace_state",
53
+ "active_ownership",
54
+ "actionable_work"
55
+ ],
56
+ "capability_evidence": {
57
+ "workspace_state": [
58
+ { "step_id": "context", "field_path": "summary.active_items" }
59
+ ],
60
+ "active_ownership": [
61
+ { "step_id": "in-progress", "field_path": "items" }
62
+ ],
63
+ "actionable_work": [{ "step_id": "open", "field_path": "items" }]
64
+ }
65
+ }
66
+ ]
67
+ },
3
68
  "tasks": [
69
+ {
70
+ "id": "orientation-context-intent",
71
+ "description": "Build sufficient cold-start workspace, ownership, and actionable-work context with the bounded orientation intent.",
72
+ "steps": [
73
+ {
74
+ "id": "context",
75
+ "args": ["context", "--for", "orient", "--limit", "10"],
76
+ "expected_exit_code": 0,
77
+ "expected_output_kind": "diagnostic",
78
+ "expected_accounting_mode": "self_reported",
79
+ "required_fields": ["summary.active_items", "hierarchy", "activity"]
80
+ }
81
+ ]
82
+ },
83
+ {
84
+ "id": "orientation-contracts-next",
85
+ "description": "Compare the proposed contracts-summary plus next cold-start protocol on the same fixed workspace.",
86
+ "steps": [
87
+ {
88
+ "id": "contracts",
89
+ "args": ["contracts", "--summary"],
90
+ "expected_exit_code": 0,
91
+ "expected_output_kind": "collection",
92
+ "expected_accounting_mode": "self_reported",
93
+ "required_fields": ["commands"]
94
+ },
95
+ {
96
+ "id": "next",
97
+ "args": ["next", "--for", "execute", "--ready-only", "--limit", "3"],
98
+ "expected_exit_code": 0,
99
+ "expected_output_kind": "diagnostic",
100
+ "expected_accounting_mode": "self_reported",
101
+ "required_fields": [
102
+ "summary.in_progress",
103
+ "held_by_others",
104
+ "recommended.id"
105
+ ]
106
+ }
107
+ ]
108
+ },
109
+ {
110
+ "id": "orientation-operating-rules",
111
+ "description": "Compare the historical context, search, open-list, and in-progress-list orientation sequence.",
112
+ "steps": [
113
+ {
114
+ "id": "context",
115
+ "args": ["context", "--for", "orient", "--limit", "10"],
116
+ "expected_exit_code": 0,
117
+ "expected_output_kind": "diagnostic",
118
+ "expected_accounting_mode": "self_reported",
119
+ "required_fields": ["summary.active_items", "hierarchy", "activity"]
120
+ },
121
+ {
122
+ "id": "search",
123
+ "args": ["search", "agent task", "--status", "all", "--limit", "10"],
124
+ "expected_exit_code": 0,
125
+ "expected_output_kind": "collection",
126
+ "expected_accounting_mode": "self_reported",
127
+ "required_fields": ["items"]
128
+ },
129
+ {
130
+ "id": "open",
131
+ "args": ["list", "--status", "open", "--limit", "20"],
132
+ "expected_exit_code": 0,
133
+ "expected_output_kind": "collection",
134
+ "expected_accounting_mode": "self_reported",
135
+ "required_fields": ["items"]
136
+ },
137
+ {
138
+ "id": "in-progress",
139
+ "args": ["list", "--status", "in_progress", "--limit", "20"],
140
+ "expected_exit_code": 0,
141
+ "expected_output_kind": "collection",
142
+ "expected_accounting_mode": "self_reported",
143
+ "required_fields": ["items"]
144
+ }
145
+ ]
146
+ },
4
147
  {
5
148
  "id": "context-bootstrap",
6
149
  "description": "Orient in a scaled workspace and inspect the canonical focus item.",
@@ -26,7 +26,7 @@ cp -R docs/examples/policy-restricted-extension .agents/pm/extensions/policy-res
26
26
  cd .agents/pm/extensions/policy-restricted-extension
27
27
  npm install
28
28
  cd -
29
- pm extension --install --project .agents/pm/extensions/policy-restricted-extension
29
+ pm package install --project .agents/pm/extensions/policy-restricted-extension
30
30
  ```
31
31
 
32
32
  Add policy in `.agents/pm/settings.json`:
@@ -68,7 +68,7 @@ Add policy in `.agents/pm/settings.json`:
68
68
  Then validate:
69
69
 
70
70
  ```bash
71
- pm extension --doctor --project --detail summary
71
+ pm package doctor --project --detail summary
72
72
  pm policy demo
73
73
  ```
74
74
 
@@ -38,7 +38,7 @@ cd -
38
38
 
39
39
  # 3) Install/activate in project scope (package-first vocabulary;
40
40
  # `pm extension --install` remains as a compatibility form)
41
- pm install .agents/pm/extensions/starter-extension --project
41
+ pm package install .agents/pm/extensions/starter-extension --project
42
42
 
43
43
  # 4) Run a starter command
44
44
  pm starter ping --name "agent"
@@ -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: 353
7
+ - Catalog error codes: 354
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: 334
12
- - Coverage fraction: 0.053824
11
+ - Uncovered error codes: 335
12
+ - Coverage fraction: 0.053672
13
13
  - Closed-domain probes: 19
14
14
  - Grammar probes: 94
15
15
 
@@ -267,6 +267,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
267
267
  | `stale_observed_signature` | `stale_observed_signature` | uncovered | none | 0 |
268
268
  | `status_duplicate` | `status_duplicate` | uncovered | none | 0 |
269
269
  | `status_invalid` | `status_invalid` | uncovered | none | 0 |
270
+ | `status_lifecycle_role_required` | `status_lifecycle_role_required` | uncovered | none | 0 |
270
271
  | `stdin_json_invalid` | `stdin_json_invalid` | uncovered | none | 0 |
271
272
  | `stdin_json_unknown_key` | `stdin_json_unknown_key` | uncovered | none | 0 |
272
273
  | `structured_event_immutable` | `structured_event_immutable` | uncovered | none | 0 |
@@ -7,12 +7,14 @@ admission reliability owned by
7
7
  Each result starts from a fresh isolated workspace containing exactly one item.
8
8
  The command runs in a fresh Node v26.5.0 process on
9
9
  linux/x64; setup and fixture generation are
10
- outside the timed interval. Short local gates use the best observed latency,
11
- while the report retains p50 and p95 evidence. RSS admission uses the measured
12
- median so one page-level outlier cannot false-fail the gate; the maximum remains
13
- in the report as diagnostic evidence. Every post-warmup RSS sample must be a
14
- finite measurement; an unavailable sample makes the admission median unavailable
15
- and fails closed when a budget exists. Admission adds a fixed 512 KiB noise margin
10
+ outside the timed interval. The default gate measures ten post-warmup fresh
11
+ processes per command and uses the best observed latency, which keeps the
12
+ immutable ratchets meaningful under transient host contention; the report
13
+ retains p50 and p95 evidence. RSS admission uses the measured median so one
14
+ page-level outlier cannot false-fail the gate; the maximum remains in the report
15
+ as diagnostic evidence. Every post-warmup RSS sample must be a finite
16
+ measurement; an unavailable sample makes the admission median unavailable and
17
+ fails closed when a budget exists. Admission adds a fixed 512 KiB noise margin
16
18
  without changing the committed budget; a majority persistent increase beyond
17
19
  that bounded margin still fails.
18
20
 
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.30"
9
+ "version": "2026.9.1"
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.30",
16
+ "version": "2026.9.1",
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.30",
3
+ "version": "2026.9.1",
4
4
  "description": "Git-native project management CLI for humans and agents.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@11.10.0",
@@ -116,13 +116,13 @@
116
116
  "test": "node scripts/run-tests.mjs test",
117
117
  "test:coverage": "node scripts/run-tests.mjs coverage",
118
118
  "test:fuzz": "node scripts/run-tests.mjs test -- tests/fuzz",
119
- "lint": "pnpm lint:eslint && pnpm lint:duplicates && pnpm lint:codefactor",
119
+ "lint": "pnpm quality:static",
120
120
  "lint:eslint": "eslint . --max-warnings=0",
121
121
  "lint:eslint:prune": "eslint . --prune-suppressions",
122
122
  "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
123
123
  "lint:duplicates": "jscpd --config .jscpd.json && jscpd --config .jscpd.source.json",
124
124
  "lint:codefactor": "pnpm quality:static",
125
- "quality:static": "pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && 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/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && 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 && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
125
+ "quality:static": "pnpm lint:eslint && pnpm lint:duplicates && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && 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/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && 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 && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
126
126
  "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs",
127
127
  "quality:recovery-closure": "pnpm build && node scripts/release/refusal-closure-gate.mjs",
128
128
  "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
@@ -231,7 +231,7 @@
231
231
  "fast-check": "^4.9.0",
232
232
  "greptile": "^3.4.2",
233
233
  "jscpd": "^5.0.16",
234
- "tsx": "^4.23.12",
234
+ "tsx": "^4.23.13",
235
235
  "typescript": "^6.0.3",
236
236
  "typescript-eslint": "^8.68.0",
237
237
  "vitest": "^4.1.11"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-beads",
3
- "version": "2026.8.30",
3
+ "version": "2026.9.1",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for importing Beads JSONL records.",