@unbrained/pm-cli 2026.8.29 → 2026.8.31

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 (136) 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 +1 -1
  15. package/CHANGELOG.md +24 -0
  16. package/dist/cli/register-list-query.js +32 -17
  17. package/dist/cli/register-operations.d.ts +2 -0
  18. package/dist/cli/register-operations.js +20 -9
  19. package/dist/cli-bundle/bundle-manifest.json +137 -137
  20. package/dist/cli-bundle/chunks/chunk-2XVV45NJ.js +35 -0
  21. package/dist/cli-bundle/chunks/{chunk-N6OR6FAR.js → chunk-3FCSFWZT.js} +12 -12
  22. package/dist/cli-bundle/chunks/{chunk-WS2GJQVG.js → chunk-52JXYSDW.js} +2 -2
  23. package/dist/cli-bundle/chunks/{chunk-TGNAA66W.js → chunk-5DH5XCJL.js} +2 -2
  24. package/dist/cli-bundle/chunks/{chunk-2UETTHY6.js → chunk-IEFJ3ZEB.js} +29 -29
  25. package/dist/cli-bundle/chunks/{chunk-MTTKAUBX.js → chunk-JIFYOJF7.js} +2 -2
  26. package/dist/cli-bundle/chunks/{chunk-3TEF3HM5.js → chunk-MWIN6OH2.js} +2 -2
  27. package/dist/cli-bundle/chunks/{chunk-GNWPTEBW.js → chunk-NW6LV3TU.js} +64 -64
  28. package/dist/cli-bundle/chunks/{chunk-7SKMLSMX.js → chunk-OUGDA7NR.js} +2 -2
  29. package/dist/cli-bundle/chunks/{chunk-2MKLQL2E.js → chunk-QZCIBZR3.js} +2 -2
  30. package/dist/cli-bundle/chunks/{chunk-CMIEDWAY.js → chunk-SXMHPK4V.js} +41 -41
  31. package/dist/cli-bundle/chunks/{register-list-query-OMKJ5ONN.js → register-list-query-7C7DKZ2U.js} +11 -11
  32. package/dist/cli-bundle/chunks/{register-mutation-QBSNCOY3.js → register-mutation-OI4BJLUX.js} +2 -2
  33. package/dist/cli-bundle/chunks/register-operations-IIMA5OKO.js +2 -0
  34. package/dist/cli-bundle/chunks/{register-setup-GLQ5SYV3.js → register-setup-52H36QCB.js} +2 -2
  35. package/dist/cli-bundle/focused-chunks/{chunk-HVQ22RC4.js → chunk-2FEZ5SKM.js} +2 -2
  36. package/dist/cli-bundle/focused-chunks/{chunk-Y3JJXRVK.js → chunk-4O4CJAR6.js} +5 -5
  37. package/dist/cli-bundle/focused-chunks/{chunk-RKOKG43G.js → chunk-APN4QN6R.js} +2 -2
  38. package/dist/cli-bundle/focused-chunks/{chunk-LYFWQMVC.js → chunk-BEVHCEWG.js} +2 -2
  39. package/dist/cli-bundle/focused-chunks/{chunk-3UMBF26I.js → chunk-BMD42PUG.js} +2 -2
  40. package/dist/cli-bundle/focused-chunks/{chunk-XXOWRJZ5.js → chunk-BPWJ4QM5.js} +2 -2
  41. package/dist/cli-bundle/focused-chunks/{chunk-G6PATS5E.js → chunk-EUTABA4M.js} +15 -15
  42. package/dist/cli-bundle/focused-chunks/{chunk-73EDXGYE.js → chunk-FOMZ6NG5.js} +2 -2
  43. package/dist/cli-bundle/focused-chunks/chunk-JCOOAUHK.js +51 -0
  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-AD6ULRAF.js → chunk-QDFJIRKN.js} +4 -4
  47. package/dist/cli-bundle/focused-chunks/{chunk-THEPQMLX.js → chunk-SVXJYD6G.js} +2 -2
  48. package/dist/cli-bundle/focused-chunks/{chunk-3AVAWVZA.js → chunk-UN34D63M.js} +2 -2
  49. package/dist/cli-bundle/focused-chunks/{chunk-TDK3OCX3.js → chunk-VJ7EFMFL.js} +2 -2
  50. package/dist/cli-bundle/main.js +2 -2
  51. package/dist/cli-bundle/sdk-authoring.js +1 -1
  52. package/dist/cli-bundle/sdk-contracts.js +1 -1
  53. package/dist/cli-bundle/sdk-core.js +29 -29
  54. package/dist/cli-bundle/sdk-governance.js +1 -1
  55. package/dist/cli-bundle/sdk-graph.js +1 -1
  56. package/dist/cli-bundle/sdk-merge.js +33 -33
  57. package/dist/cli-bundle/sdk-query.js +1 -1
  58. package/dist/cli-bundle/sdk-runtime.js +1 -1
  59. package/dist/cli-bundle/sdk-testing.js +1 -1
  60. package/dist/cli-bundle/sdk.js +9 -9
  61. package/dist/core/schema/runtime-schema.d.ts +4 -0
  62. package/dist/core/schema/runtime-schema.js +60 -48
  63. package/dist/core/schema/status-defs-file.js +5 -2
  64. package/dist/mcp/legacy-adapter.d.ts +11 -2
  65. package/dist/mcp/legacy-adapter.js +26 -12
  66. package/dist/sdk/cli-contracts/flag-contracts.d.ts +2 -0
  67. package/dist/sdk/cli-contracts/flag-contracts.js +6 -2
  68. package/dist/sdk/cli-contracts/grammar-contracts.d.ts +1 -1
  69. package/dist/sdk/cli-contracts/grammar-contracts.js +12 -2
  70. package/dist/sdk/cli-contracts/runtime-contracts.js +3 -2
  71. package/dist/sdk/cli-contracts/tool-schema.js +11 -3
  72. package/dist/sdk/generated/generated-error-code-catalog-part-2.js +14 -2
  73. package/dist/sdk/governance/health.js +17 -6
  74. package/dist/sdk/governance/status-role-diagnostics.d.ts +27 -0
  75. package/dist/sdk/governance/status-role-diagnostics.js +36 -0
  76. package/dist/sdk/governance/validate-normalization.d.ts +6 -0
  77. package/dist/sdk/governance/validate-normalization.js +37 -0
  78. package/dist/sdk/governance/validate.d.ts +1 -1
  79. package/dist/sdk/governance/validate.js +20 -35
  80. package/dist/sdk/governance/workspace-position.d.ts +69 -0
  81. package/dist/sdk/governance/workspace-position.js +164 -0
  82. package/dist/sdk/governance.d.ts +2 -0
  83. package/dist/sdk/governance.js +4 -2
  84. package/dist/sdk/index.d.ts +1 -1
  85. package/dist/sdk/index.js +3 -3
  86. package/dist/sdk/mcp/protocol.d.ts +10 -2
  87. package/dist/sdk/mcp/protocol.js +15 -4
  88. package/dist/sdk/query/context.js +11 -14
  89. package/dist/sdk/query/list.d.ts +2 -0
  90. package/dist/sdk/query/list.js +33 -12
  91. package/dist/sdk/runtime-extended-actions.js +8 -4
  92. package/dist/sdk/schema.js +12 -2
  93. package/dist/sdk/test/execution.d.ts +15 -0
  94. package/dist/sdk/test/execution.js +35 -27
  95. package/docs/AGENT_GUIDE.md +1 -1
  96. package/docs/AGENT_PROVENANCE_ADR.md +1 -1
  97. package/docs/AGENT_RUNTIME_PRIMITIVES.md +2 -2
  98. package/docs/CLAUDE_CODE_PLUGIN.md +3 -3
  99. package/docs/COMMANDS.md +12 -12
  100. package/docs/CONFIGURATION.md +1 -1
  101. package/docs/DEFECT_RECURRENCE.md +2 -0
  102. package/docs/MCP_2026_07_28.md +28 -8
  103. package/docs/MCP_2026_07_28_CONFORMANCE.md +1 -0
  104. package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md +4 -2
  105. package/docs/ONBOARDING.md +1 -1
  106. package/docs/README.md +2 -1
  107. package/docs/READ_OUTPUT_CONTRACTS.md +1 -1
  108. package/docs/RECURRENCE_RECOVERY_CONTRACTS.md +1 -1
  109. package/docs/SDK.md +3 -3
  110. package/docs/TESTING.md +23 -14
  111. package/docs/WORKSPACE_POSITION_AND_LIFECYCLE.md +113 -0
  112. package/docs/examples/policy-restricted-extension/README.md +2 -2
  113. package/docs/examples/starter-extension/README.md +1 -1
  114. package/docs/generated/REFUSAL_CLOSURE_CENSUS.md +4 -3
  115. package/marketplace.json +2 -2
  116. package/package.json +4 -4
  117. package/packages/pm-beads/package.json +1 -1
  118. package/packages/pm-calendar/package.json +1 -1
  119. package/packages/pm-command-kit/package.json +1 -1
  120. package/packages/pm-digital-twin/package.json +1 -1
  121. package/packages/pm-governance-audit/package.json +1 -1
  122. package/packages/pm-guide-shell/package.json +1 -1
  123. package/packages/pm-kanban/package.json +1 -1
  124. package/packages/pm-lifecycle-hooks/package.json +1 -1
  125. package/packages/pm-linked-test-adapters/package.json +1 -1
  126. package/packages/pm-search-advanced/package.json +1 -1
  127. package/packages/pm-templates/package.json +1 -1
  128. package/packages/pm-todos/package.json +1 -1
  129. package/packages/pm-vcs/package.json +1 -1
  130. package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
  131. package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
  132. package/sdk/public-surface.json +171 -10
  133. package/dist/cli-bundle/chunks/chunk-7X6OZEIV.js +0 -34
  134. package/dist/cli-bundle/chunks/register-operations-UC77FQZC.js +0 -2
  135. package/dist/cli-bundle/focused-chunks/chunk-AXZ5AJAF.js +0 -50
  136. package/dist/cli-bundle/focused-chunks/chunk-LLNTHF5X.js +0 -2
package/docs/SDK.md CHANGED
@@ -137,7 +137,7 @@ List consumers can inspect `LIST_COMMAND_DEFAULT_PROJECTIONS` instead of
137
137
  copying command-specific defaults. Every compact or field-projected list result
138
138
  now echoes the applied `projection`; `brief` remains distinct from `compact`,
139
139
  and `DEFAULT_COMPACT_LIST_FIELDS` / `BRIEF_LIST_FIELDS` provide the canonical
140
- field sets. `pm contracts --command list-open --flags-only --json` includes the
140
+ field sets. `pm contracts --command list --flags-only --json` includes the
141
141
  same per-command projection surface.
142
142
 
143
143
  ### Public-surface compatibility
@@ -336,7 +336,7 @@ Command/action contract exports:
336
336
  - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
337
337
  - Annotation kernel primitives: `resolveAnnotationInput`, `runAnnotationCommand`, `resolveAnnotationIndex`, `parseAnnotationTextInput`, `limitAnnotationEntries`, `readAnnotationEntries`, `wrapOwnershipConflict`, `isErrnoError`, and their typed input/config/result contracts
338
338
  - Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, `assertLinkedArtifactMutationIsUnambiguous`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations. A transaction that resolves one path into both its add and remove sets fails before item or history mutation; split an intentional replacement into two commands so its context remains explicit.
339
- - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
339
+ - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list --status blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
340
340
  - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
341
341
  - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
342
342
  - Built-in `recurs_from` records that the source is a later occurrence of the target. Its registry contract is directed, `source_after_target`, non-ordering, many-to-many, and persistent across terminal lifecycle states. Local mutation paths enforce strictly later source `created_at` metadata before item or history persistence and return structured source/target evidence when chronology is equal, reversed, or unverifiable. It therefore connects an incident family for traversal and analytics without reclassifying `supersedes` replacements or `duplicate_of` identity collapse.
@@ -1642,7 +1642,7 @@ const certified = certifyCompleteListResult(candidate);
1642
1642
 
1643
1643
  `PmCompleteListValidationError.receipt` lists every failed invariant and carries
1644
1644
  the exact recovery command
1645
- `pm list-all --full --strict-read --no-truncate --output-budget unbounded --json`.
1645
+ `pm list --all --full --strict-read --no-truncate --output-budget unbounded --json`.
1646
1646
  The helper never infers completeness from a large limit: derived-index reads,
1647
1647
  terminal-state filtering, duplicate ids, cursor/session projection, compaction,
1648
1648
  and any omission receipt all prevent certification.
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.
@@ -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 |
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.29"
9
+ "version": "2026.8.31"
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.29",
16
+ "version": "2026.8.31",
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.29",
3
+ "version": "2026.8.31",
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",
@@ -227,7 +227,7 @@
227
227
  "esbuild": "0.28.2",
228
228
  "eslint": "^10.9.1",
229
229
  "eslint-plugin-sonarjs": "^4.2.0",
230
- "eslint-plugin-unicorn": "^73.0.0",
230
+ "eslint-plugin-unicorn": "74.0.0",
231
231
  "fast-check": "^4.9.0",
232
232
  "greptile": "^3.4.2",
233
233
  "jscpd": "^5.0.16",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-beads",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for importing Beads JSONL records.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-calendar",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for calendar and agenda views.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-command-kit",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-digital-twin",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-governance-audit",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for governance audit and normalization workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-guide-shell",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for guide and shell completion workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-kanban",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-lifecycle-hooks",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package demonstrating safe lifecycle hook registration.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-linked-test-adapters",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for optional linked-test run management adapters and reporters.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-search-advanced",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-templates",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for reusable create templates.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-todos",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for Todo markdown import and export.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-vcs-sdk-exemplar",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pm-claude",
3
3
  "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
4
- "version": "2026.8.29",
4
+ "version": "2026.8.31",
5
5
  "author": {
6
6
  "name": "unbrained",
7
7
  "url": "https://github.com/unbraind/pm-cli"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pm-codex",
3
- "version": "2026.8.29",
3
+ "version": "2026.8.31",
4
4
  "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
5
5
  "author": {
6
6
  "name": "unbrained",