@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.
- package/.agents/skills/HARNESS_COMPATIBILITY.md +1 -1
- package/.agents/skills/README.md +1 -1
- package/.agents/skills/pm-developer/SKILL.md +1 -1
- package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md +2 -2
- package/.agents/skills/pm-developer/references/MULTI_AGENT_MERGE.md +1 -1
- package/.agents/skills/pm-developer/references/TOKEN_BUDGETS.md +1 -1
- package/.agents/skills/pm-extensions/SKILL.md +2 -2
- package/.agents/skills/pm-extensions/references/AUTHORING.md +1 -1
- package/.agents/skills/pm-extensions/references/LIFECYCLE.md +1 -1
- package/.agents/skills/pm-sdk/SKILL.md +1 -1
- package/.agents/skills/pm-user/SKILL.md +2 -2
- package/.agents/skills/pm-user/references/WORKFLOWS.md +2 -2
- package/.claude-plugin/marketplace.json +2 -2
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +24 -0
- package/dist/cli/register-list-query.js +32 -17
- package/dist/cli/register-operations.d.ts +2 -0
- package/dist/cli/register-operations.js +20 -9
- package/dist/cli-bundle/bundle-manifest.json +137 -137
- package/dist/cli-bundle/chunks/chunk-2XVV45NJ.js +35 -0
- package/dist/cli-bundle/chunks/{chunk-N6OR6FAR.js → chunk-3FCSFWZT.js} +12 -12
- package/dist/cli-bundle/chunks/{chunk-WS2GJQVG.js → chunk-52JXYSDW.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-TGNAA66W.js → chunk-5DH5XCJL.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-2UETTHY6.js → chunk-IEFJ3ZEB.js} +29 -29
- package/dist/cli-bundle/chunks/{chunk-MTTKAUBX.js → chunk-JIFYOJF7.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-3TEF3HM5.js → chunk-MWIN6OH2.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-GNWPTEBW.js → chunk-NW6LV3TU.js} +64 -64
- package/dist/cli-bundle/chunks/{chunk-7SKMLSMX.js → chunk-OUGDA7NR.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-2MKLQL2E.js → chunk-QZCIBZR3.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-CMIEDWAY.js → chunk-SXMHPK4V.js} +41 -41
- package/dist/cli-bundle/chunks/{register-list-query-OMKJ5ONN.js → register-list-query-7C7DKZ2U.js} +11 -11
- package/dist/cli-bundle/chunks/{register-mutation-QBSNCOY3.js → register-mutation-OI4BJLUX.js} +2 -2
- package/dist/cli-bundle/chunks/register-operations-IIMA5OKO.js +2 -0
- package/dist/cli-bundle/chunks/{register-setup-GLQ5SYV3.js → register-setup-52H36QCB.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-HVQ22RC4.js → chunk-2FEZ5SKM.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-Y3JJXRVK.js → chunk-4O4CJAR6.js} +5 -5
- package/dist/cli-bundle/focused-chunks/{chunk-RKOKG43G.js → chunk-APN4QN6R.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-LYFWQMVC.js → chunk-BEVHCEWG.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-3UMBF26I.js → chunk-BMD42PUG.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-XXOWRJZ5.js → chunk-BPWJ4QM5.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-G6PATS5E.js → chunk-EUTABA4M.js} +15 -15
- package/dist/cli-bundle/focused-chunks/{chunk-73EDXGYE.js → chunk-FOMZ6NG5.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-JCOOAUHK.js +51 -0
- package/dist/cli-bundle/focused-chunks/chunk-JEFKLWMM.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-JZYPPMXF.js → chunk-KB5OFSFD.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-AD6ULRAF.js → chunk-QDFJIRKN.js} +4 -4
- package/dist/cli-bundle/focused-chunks/{chunk-THEPQMLX.js → chunk-SVXJYD6G.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-3AVAWVZA.js → chunk-UN34D63M.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-TDK3OCX3.js → chunk-VJ7EFMFL.js} +2 -2
- package/dist/cli-bundle/main.js +2 -2
- 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 +29 -29
- 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 +33 -33
- 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 +9 -9
- package/dist/core/schema/runtime-schema.d.ts +4 -0
- package/dist/core/schema/runtime-schema.js +60 -48
- package/dist/core/schema/status-defs-file.js +5 -2
- package/dist/mcp/legacy-adapter.d.ts +11 -2
- package/dist/mcp/legacy-adapter.js +26 -12
- package/dist/sdk/cli-contracts/flag-contracts.d.ts +2 -0
- package/dist/sdk/cli-contracts/flag-contracts.js +6 -2
- package/dist/sdk/cli-contracts/grammar-contracts.d.ts +1 -1
- package/dist/sdk/cli-contracts/grammar-contracts.js +12 -2
- package/dist/sdk/cli-contracts/runtime-contracts.js +3 -2
- package/dist/sdk/cli-contracts/tool-schema.js +11 -3
- package/dist/sdk/generated/generated-error-code-catalog-part-2.js +14 -2
- package/dist/sdk/governance/health.js +17 -6
- package/dist/sdk/governance/status-role-diagnostics.d.ts +27 -0
- package/dist/sdk/governance/status-role-diagnostics.js +36 -0
- package/dist/sdk/governance/validate-normalization.d.ts +6 -0
- package/dist/sdk/governance/validate-normalization.js +37 -0
- package/dist/sdk/governance/validate.d.ts +1 -1
- package/dist/sdk/governance/validate.js +20 -35
- package/dist/sdk/governance/workspace-position.d.ts +69 -0
- package/dist/sdk/governance/workspace-position.js +164 -0
- package/dist/sdk/governance.d.ts +2 -0
- package/dist/sdk/governance.js +4 -2
- package/dist/sdk/index.d.ts +1 -1
- package/dist/sdk/index.js +3 -3
- package/dist/sdk/mcp/protocol.d.ts +10 -2
- package/dist/sdk/mcp/protocol.js +15 -4
- package/dist/sdk/query/context.js +11 -14
- package/dist/sdk/query/list.d.ts +2 -0
- package/dist/sdk/query/list.js +33 -12
- package/dist/sdk/runtime-extended-actions.js +8 -4
- package/dist/sdk/schema.js +12 -2
- package/dist/sdk/test/execution.d.ts +15 -0
- package/dist/sdk/test/execution.js +35 -27
- package/docs/AGENT_GUIDE.md +1 -1
- package/docs/AGENT_PROVENANCE_ADR.md +1 -1
- package/docs/AGENT_RUNTIME_PRIMITIVES.md +2 -2
- package/docs/CLAUDE_CODE_PLUGIN.md +3 -3
- package/docs/COMMANDS.md +12 -12
- package/docs/CONFIGURATION.md +1 -1
- package/docs/DEFECT_RECURRENCE.md +2 -0
- package/docs/MCP_2026_07_28.md +28 -8
- package/docs/MCP_2026_07_28_CONFORMANCE.md +1 -0
- package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md +4 -2
- package/docs/ONBOARDING.md +1 -1
- package/docs/README.md +2 -1
- package/docs/READ_OUTPUT_CONTRACTS.md +1 -1
- package/docs/RECURRENCE_RECOVERY_CONTRACTS.md +1 -1
- package/docs/SDK.md +3 -3
- package/docs/TESTING.md +23 -14
- package/docs/WORKSPACE_POSITION_AND_LIFECYCLE.md +113 -0
- package/docs/examples/policy-restricted-extension/README.md +2 -2
- package/docs/examples/starter-extension/README.md +1 -1
- package/docs/generated/REFUSAL_CLOSURE_CENSUS.md +4 -3
- package/marketplace.json +2 -2
- package/package.json +4 -4
- 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 +171 -10
- package/dist/cli-bundle/chunks/chunk-7X6OZEIV.js +0 -34
- package/dist/cli-bundle/chunks/register-operations-UC77FQZC.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-AXZ5AJAF.js +0 -50
- 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
|
|
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
|
|
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
|
|
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
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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`
|
|
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
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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:
|
|
12
|
-
- Coverage fraction: 0.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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": "
|
|
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-digital-twin",
|
|
3
|
-
"version": "2026.8.
|
|
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,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.31",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "unbrained",
|
|
7
7
|
"url": "https://github.com/unbraind/pm-cli"
|