@unbrained/pm-cli 2026.8.30 → 2026.8.31

package/.agents/skills/HARNESS_COMPATIBILITY.md

@@ -26,7 +26,7 @@ Use the same low-token route in every harness:
 Before release, run:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide skills --depth standard
 node scripts/release/docs-skills-gate.mjs
 ```

package/.agents/skills/README.md

@@ -35,7 +35,7 @@ contracts.
 ## Runtime Routing
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide                       # topic index
 pm guide skills
 pm guide harnesses --depth standard

package/.agents/skills/pm-developer/SKILL.md

@@ -34,7 +34,7 @@ routed into by section from the references below.
 Optional deep routing that never goes stale:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide workflows --depth brief
 ```
 

package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md

@@ -15,7 +15,7 @@ pnpm build
 ```bash
 pm context --limit 10
 pm search "<keywords>" --limit 10
-pm list-open --limit 20
+pm list --status open --limit 20
 pm claim <ID>
 pm update <ID> --status in_progress --description "..."
 pm append <ID> --body "Implementation notes"
@@ -42,7 +42,7 @@ pm release <ID>
 ## Local Docs Routing
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide workflows
 pm guide commands --depth standard
 pm guide release --json

package/.agents/skills/pm-developer/references/MULTI_AGENT_MERGE.md

@@ -22,7 +22,7 @@ Skipping this is the single most common cause of tracker merge conflicts.
 - `pm claim <ID>` before substantial edits. A claim is a recorded lease, not a
   lock file, and it survives branching.
 - `pm release <ID>` when pausing, handing off, closing, or canceling.
-- `pm list-in-progress` shows what the fleet currently holds.
+- `pm list --status in_progress` shows what the fleet currently holds.
 - Never force an ownership or lock override without explicit human approval.
 
 Author identity is detected per invocation — harness, model, effort, role, and

package/.agents/skills/pm-developer/references/TOKEN_BUDGETS.md

@@ -81,5 +81,5 @@ pm next                 # ~2.5k tok — one actionable item with its context
 pm contracts --summary  # ~2.6k tok — the command surface with per-command ceilings
 ```
 
-Prefer `pm next` over `pm list-open` when the goal is to start work: it applies
+Prefer `pm next` over `pm list --status open` when the goal is to start work: it applies
 relevance ranking and returns a working set rather than a page of rows.

package/.agents/skills/pm-extensions/SKILL.md

@@ -29,7 +29,7 @@ profiles over the same substrate.
 Optional deep routing that never goes stale:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide extensions
 ```
 
@@ -59,7 +59,7 @@ pm contracts --runtime-only --availability-only
 pm package explore --project              # inspect state first
 pm package manage --detail summary
 pm package doctor --detail deep
-pm install <package> --project            # then mutate
+pm package install <package> --project            # then mutate
 pm contracts --command <extension-command> --flags-only
 pm package doctor --detail deep           # verify after
 ```

package/.agents/skills/pm-extensions/references/AUTHORING.md

@@ -74,7 +74,7 @@ moment the package publishes.
 ```bash
 pm package init <name>                       # scaffold
 # ...implement extensions/*.ts...
-pm install <path-or-name> --project          # install locally
+pm package install <path-or-name> --project          # install locally
 pm package doctor --detail deep              # activation diagnostics
 pm contracts --command <your-command> --flags-only
 pm <your-command> --help --json              # the contract a consumer will read

package/.agents/skills/pm-extensions/references/LIFECYCLE.md

@@ -11,7 +11,7 @@ pm package doctor --detail deep
 ## Install and Activate
 
 ```bash
-pm install <target> --project
+pm package install <target> --project
 pm package activate <target> --project
 pm package doctor --detail summary
 ```

package/.agents/skills/pm-sdk/SKILL.md

@@ -29,7 +29,7 @@ integration should never import repository internals to get it.
 Optional deep routing that never goes stale:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide sdk
 pm guide tokens --depth brief
 ```

package/.agents/skills/pm-user/SKILL.md

@@ -28,7 +28,7 @@ agent can rebuild the full situation from it alone.
 Optional deep routing that never goes stale:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide quickstart
 pm guide commands --depth brief
 ```
@@ -47,7 +47,7 @@ pm guide commands --depth brief
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20 --output-include id,title,type,priority
+pm list --status open --limit 20 --brief
 # reuse if it exists; otherwise create with lineage
 pm create --create-mode progressive \
   --title "..." --description "..." --type Task --status open \

package/.agents/skills/pm-user/references/WORKFLOWS.md

@@ -7,8 +7,8 @@
 ```bash
 pm context --limit 10
 pm search "<keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 2. If existing item matches, reuse and update it.

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.30"
+    "version": "2026.8.31"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "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.",
-      "version": "2026.8.30",
+      "version": "2026.8.31",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -19,7 +19,7 @@ Use runtime contracts for exact flags because packages and settings can change t
 ```bash
 pm <command> --help --json
 pm contracts --command <command> --flags-only --json
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide <topic>
 ```
 

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026.8.31 - 2026-08-31
+
+### Added
+
+- Workspace position read: one bounded answer to where this workspace stands in the branch-and-merge workflow and what to run next, replacing a protocol the agent must remember ([pm-bq0ii8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-bq0ii8.toon))
+
+### Fixed
+
+- Custom statuses registered without a lifecycle role are silently orphaned from every work-selection surface ([pm-0mhspz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0mhspz.toon))
+- GH-1158: Windows Node 24 nightly receipt fixture derives a root-relative expectation from a drive-qualified path ([pm-46hpx8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-46hpx8.toon))
+- GH-1154: linked-test sandbox guard is command-shape inconsistent and undocumented ([pm-s8cth5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-s8cth5.toon))
+- The local preflight token-budget gate is red on a workstation and green in hosted CI for the same commit again, because the earlier remediation closed the one ambient channel that had bitten instead of closing the fixture's environment ([pm-4o7tlx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4o7tlx.toon))
+- The bounded legacy MCP compatibility set stops one revision short of the spec's own legacy boundary, so every current host is refused at initialize and the dual-era guarantee is unmet ([pm-edywqn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-edywqn.toon))
+
+### Deprecated
+
+- The project's own agent-facing documentation and skills instruct deprecated command spellings, so the alias-usage signal that decides when a spelling can be retired is manufactured by the instructions rather than observed from callers ([pm-q2n4vd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-q2n4vd.toon))
+
 ## 2026.8.30 - 2026-08-30
 
 ### Other

package/dist/cli/register-list-query.js

@@ -1,11 +1,11 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="102d4534-fb3a-57a3-91d1-db344492b812")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1c6a0524-a8eb-5a20-b395-b488249c4e83")}catch(e){}}();
 import { EXIT_CODE, PmCliError, readSettings, renderRowsAsCsv, renderRowsAsTable, resolvePmRoot, } from "../sdk/runtime-primitives.js";
 import { renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "../sdk/cli-contracts.js";
 import { EVAL_QUERY_SET_SCHEMA_ID } from "../sdk/eval.js";
 import { applyContextIntentProjection } from "../sdk/context-intent-contracts.js";
 import { renderPmClosedDomainHelp } from "../sdk/agent/closed-domain-contracts.js";
-import { serializeNdjsonRows, serializeNdjsonStream, } from "../sdk/output.js";
+import { serializeNdjsonRows, serializeNdjsonStream } from "../sdk/output.js";
 import { listMutationEvents, subscribeMutationEventBatches, subscribeMutationEvents, } from "../sdk/mutation-events.js";
 import { runActivity } from "./commands/activity.js";
 import { runAggregate } from "./commands/aggregate.js";
@@ -169,6 +169,22 @@ async function runRegisteredListCommand(params) {
     }
     const intentOptions = applyContextIntentProjection("list", params.options);
     const listOptions = normalizeListOptions(intentOptions);
+    const selection = resolveRegisteredListSelection(params, listOptions);
+    const { effectiveName, effectiveStatus, effectiveDependencyBlocked, effectiveExcludeTerminal, } = selection;
+    applyDefaultListProjection(listOptions, effectiveName);
+    Object.assign(listOptions, { projectionCommand: effectiveName });
+    if (effectiveExcludeTerminal)
+        listOptions.excludeTerminal = true;
+    listOptions.dependencyBlocked = effectiveDependencyBlocked;
+    const output = resolveRegisteredListOutputContext(intentOptions, globalOptions);
+    const result = await runList(effectiveDependencyBlocked ? undefined : effectiveStatus, listOptions, globalOptions);
+    renderRegisteredListResult("list", result, output);
+    if (globalOptions.profile) {
+        printError(`profile:command=list took_ms=${Date.now() - startedAt}`);
+    }
+}
+/** Resolve aliases and lifecycle buckets into one SDK list selection. */
+function resolveRegisteredListSelection(params, listOptions) {
     let effectiveName = params.name;
     let effectiveStatus = params.status;
     let effectiveDependencyBlocked = params.dependencyBlocked === true;
@@ -183,7 +199,8 @@ async function runRegisteredListCommand(params) {
             effectiveExcludeTerminal = false;
             listOptions.status = undefined;
         }
-        else if (requestedStatus !== undefined && requestedVariant !== undefined) {
+        else if (requestedStatus !== undefined &&
+            requestedVariant !== undefined) {
             effectiveName = requestedVariant.name;
             effectiveStatus = requestedStatus;
             effectiveDependencyBlocked = requestedVariant.dependencyBlocked;
@@ -191,17 +208,17 @@ async function runRegisteredListCommand(params) {
             listOptions.status = undefined;
         }
     }
-    applyDefaultListProjection(listOptions, effectiveName);
-    Object.assign(listOptions, { projectionCommand: effectiveName });
-    if (effectiveExcludeTerminal)
-        listOptions.excludeTerminal = true;
-    listOptions.dependencyBlocked = effectiveDependencyBlocked;
-    const output = resolveRegisteredListOutputContext(intentOptions, globalOptions);
-    const result = await runList(effectiveDependencyBlocked ? undefined : effectiveStatus, listOptions, globalOptions);
-    renderRegisteredListResult("list", result, output);
-    if (globalOptions.profile) {
-        printError(`profile:command=list took_ms=${Date.now() - startedAt}`);
+    if (effectiveName === "list-open" || effectiveName === "list-in-progress") {
+        listOptions.lifecycleBucket =
+            effectiveName === "list-open" ? "open" : "in_progress";
+        effectiveStatus = undefined;
     }
+    return {
+        effectiveName,
+        effectiveStatus,
+        effectiveDependencyBlocked,
+        effectiveExcludeTerminal,
+    };
 }
 function registerListCommand(program, descriptor) {
     const { name, description, status, excludeTerminal, allowStatusFilter, dependencyBlocked, aliasContract, } = descriptor;
@@ -465,9 +482,7 @@ function buildMutationEventOptions(options, pmRoot) {
         limit: typeof options.limit === "string" ? Number(options.limit) : undefined,
         full: options.full === true,
         ...(options.provenance === true ? { provenance: true } : {}),
-        ...(options.provenanceSummary === true
-            ? { provenanceSummary: true }
-            : {}),
+        ...(options.provenanceSummary === true ? { provenanceSummary: true } : {}),
         ...(harness === undefined ? {} : { harness }),
         ...(agentInstance === undefined ? {} : { agentInstance }),
         ...(provenanceFilter === undefined ? {} : { provenanceFilter }),
@@ -924,4 +939,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=102d4534-fb3a-57a3-91d1-db344492b812
+//# debugId=1c6a0524-a8eb-5a20-b395-b488249c4e83

package/dist/cli/register-operations.d.ts

@@ -53,6 +53,7 @@ declare function buildRunTestOptions(options: Record<string, unknown>, values: {
 export declare const _testOnlyRegisterOperations: {
     buildRunTestOptions: typeof buildRunTestOptions;
     buildRunTestAllOptions: typeof buildRunTestAllOptions;
+    runWorkspacePositionAction: typeof runWorkspacePositionAction;
     validateBackgroundTestOptions: typeof validateBackgroundTestOptions;
 };
 declare function buildRunTestAllOptions(options: Record<string, unknown>): {
@@ -76,6 +77,7 @@ declare function buildRunTestAllOptions(options: Record<string, unknown>): {
     checkContext: boolean;
     autoPmContext: boolean;
 };
+declare function runWorkspacePositionAction(_options: Record<string, unknown>, command: Command): Promise<void>;
 /** Enforces the claim target XOR selection contract before dispatch. */
 export declare function requireClaimTarget(id: string | undefined, next: boolean): void;
 /** Implements register operation commands for the public runtime surface of this module. */

package/dist/cli/register-operations.js

@@ -1,9 +1,10 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7377fa65-aaa9-5d28-b3fb-a8becaf0d484")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ecf75f5d-6345-5487-b7e4-1bd8f97326fd")}catch(e){}}();
 import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, createUnknownSubcommandError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
 import { resolveStartTaskInProgressStatus } from "../sdk/start-task-status.js";
 import { parseStatsAnalyticsJson } from "./stats-analytics-json.js";
 import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, WORKSPACE_SNAPSHOT_ACTIONS, } from "../sdk/workspace-snapshot.js";
+import { readWorkspacePosition } from "../sdk/governance/workspace-position.js";
 import { runClaim, runClaimNext, runRelease } from "./commands/claim.js";
 import { runClose } from "./commands/close.js";
 import { runContracts } from "./commands/contracts.js";
@@ -141,6 +142,7 @@ function buildRunTestOptions(options, values) {
 export const _testOnlyRegisterOperations = {
     buildRunTestOptions,
     buildRunTestAllOptions,
+    runWorkspacePositionAction,
     validateBackgroundTestOptions,
 };
 async function runForegroundLinkedTests(id, options, globalOptions, values) {
@@ -308,7 +310,7 @@ async function runHealthAction(options, command) {
     const strictExit = Boolean(options.strictExit) || Boolean(options.failOnWarn);
     const result = await runHealth(globalOptions, {
         strictDirectories: Boolean(options.strictDirectories),
-        requireMergeDrivers: Boolean(options.requireMergeDrivers),
+        requireMergeDrivers: Boolean(options.requireMergeDrivers) || strictExit,
         checkOnly: Boolean(options.checkOnly),
         checkTelemetry: Boolean(options.checkTelemetry),
         noRefresh: Boolean(options.noRefresh),
@@ -446,6 +448,10 @@ async function runWorkspaceSnapshotAction(action, target, options, command) {
     }
     printResult(await deleteWorkspaceSnapshot(pmRoot, target), globalOptions);
 }
+async function runWorkspacePositionAction(_options, command) {
+    const globalOptions = getGlobalOptions(command);
+    printResult(await readWorkspacePosition(globalOptions), globalOptions);
+}
 async function runContractsAction(options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
@@ -595,8 +601,8 @@ export function registerOperationCommands(program) {
     const testCommand = program
         .command("test")
         .argument("<id>", "Item id")
-        .option("--add <value>", "Add linked test entry (CSV/markdown pairs or - for stdin)", collect)
-        .option("--add-json <value>", "Add linked test entry from JSON object/array (or - for stdin)", collect)
+        .option("--add <value>", "Add verified isolated test (CSV/markdown or stdin)", collect)
+        .option("--add-json <value>", "Add verified isolated test (JSON object/array or stdin)", collect)
         .option("--remove <value>", "Remove linked test entry by exact command/path (command=<value> and path=<value> preserve commas and equals signs; or - for stdin)", collect)
         .option("--remove-index <n>", "Remove the 1-based linked-test index from --list order (repeatable)", collect)
         .option("--list", "List linked tests without mutating")
@@ -712,13 +718,18 @@ export function registerOperationCommands(program) {
         .option("--scope <value>", "Limit cleanup to one or more scopes (comma-separated or repeatable): index, embeddings, runtime, locks, checkpoints, transactions", collect)
         .description("Delete optional cache artifacts by default (including expired lock debris) and show a summary.")
         .action(runGcAction);
-    program
+    const workspaceCommand = program
         .command("workspace")
-        .description("Manage portable workspace-level SDK primitives.")
+        .description("Inspect workspace state and snapshots.");
+    workspaceCommand
+        .command("position")
+        .description("Show merge and history readiness.")
+        .action(runWorkspacePositionAction);
+    workspaceCommand
         .command("snapshot")
-        .argument("<action>", "Snapshot action: create, list, inspect, restore, delete")
+        .argument("<action>", "Action: create, list, inspect, restore, delete")
         .argument("[target]", "Optional name for create; name or fingerprint otherwise")
-        .description("Create, inspect, list, restore, or delete content-addressed tracker snapshots.")
+        .description("Manage content-addressed tracker snapshots.")
         .option("--dry-run", "Preview restore file, item, stream, and history-entry impact without mutating state")
         .option("--force", "Explicitly confirm a whole-workspace snapshot restore")
         .option("--author <value>", "Actor recorded on the restore audit event")
@@ -898,4 +909,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=7377fa65-aaa9-5d28-b3fb-a8becaf0d484
+//# debugId=ecf75f5d-6345-5487-b7e4-1bd8f97326fd