@unbrained/pm-cli 2026.8.29 → 2026.8.31

package/dist/sdk/query/list.js

@@ -4,7 +4,7 @@
  * Implements the pm list command surface and its agent-facing runtime behavior.
  */
 
-!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]="93e8c187-e198-50fc-bf2c-7dae2ea42219")}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]="ccdb7d16-4f38-58d4-a19d-4ab1516cb1d7")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
@@ -978,20 +978,40 @@ function resolveListOrderingOptions(options) {
 }
 function resolveListStatusSelection(status, options, statusRegistry) {
     const explicitStatus = resolveStatusFilter(options.status, statusRegistry);
-    const resolvedStatus = explicitStatus ?? resolveStatusFilter(status, statusRegistry);
+    let lifecycleStatus;
+    if (options.lifecycleBucket === "in_progress") {
+        lifecycleStatus = [statusRegistry.in_progress_status];
+    }
+    else if (options.lifecycleBucket === "open") {
+        lifecycleStatus = [...statusRegistry.active_statuses]
+            .filter((entry) => entry !== statusRegistry.in_progress_status)
+            .sort((left, right) => left.localeCompare(right));
+    }
+    const resolvedStatus = explicitStatus ??
+        lifecycleStatus ??
+        resolveStatusFilter(status, statusRegistry);
     const explicitAllStatuses = isStatusAllFilterInput(options.status);
     const effectiveOptions = explicitStatus || explicitAllStatuses
         ? { ...options, excludeTerminal: false }
         : options;
-    const filtersStatus = explicitAllStatuses
-        ? "all"
-        : resolvedStatus === undefined
-            ? effectiveOptions.excludeTerminal === true
-                ? null
-                : "all"
-            : resolvedStatus.length === 1
-                ? resolvedStatus[0]
-                : resolvedStatus;
+    let filtersStatus = "all";
+    if (explicitAllStatuses) {
+        filtersStatus = "all";
+    }
+    else if (explicitStatus !== undefined) {
+        filtersStatus =
+            explicitStatus.length === 1 ? explicitStatus[0] : explicitStatus;
+    }
+    else if (options.lifecycleBucket !== undefined) {
+        filtersStatus = options.lifecycleBucket;
+    }
+    else if (resolvedStatus !== undefined) {
+        filtersStatus =
+            resolvedStatus.length === 1 ? resolvedStatus[0] : resolvedStatus;
+    }
+    else if (effectiveOptions.excludeTerminal === true) {
+        filtersStatus = null;
+    }
     return {
         resolvedStatus,
         explicitAllStatuses,
@@ -1045,6 +1065,7 @@ async function tryLoadIndexedListPage(params) {
         "includeBody",
         "excludeTerminal",
         "dependencyBlocked",
+        "lifecycleBucket",
         "noTruncate",
         "projectionCommand",
         "truncate",
@@ -1281,4 +1302,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=93e8c187-e198-50fc-bf2c-7dae2ea42219
+//# debugId=ccdb7d16-4f38-58d4-a19d-4ab1516cb1d7

package/dist/sdk/runtime-extended-actions.js

@@ -1,8 +1,8 @@
 
-!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]="8a3a82a1-9e3d-555f-9111-3c3e19887f75")}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]="95e9def9-3f48-5108-8a17-0747fcf64f2d")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
-import { transferMutationStdinTokenPolicy, } from "./runtime-primitives.js";
+import { transferMutationStdinTokenPolicy } from "./runtime-primitives.js";
 import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { runEval } from "./eval.js";
@@ -14,6 +14,7 @@ import { listMutationEvents } from "./mutation-events.js";
 import { parseRuntimeInteger, readRuntimeString, readRuntimeStringArray, } from "./runtime-input.js";
 import { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, } from "./workspace-snapshot.js";
+import { readWorkspacePosition } from "./governance/workspace-position.js";
 function mergedInput(context) {
     const input = { ...context.args, ...context.options };
     return transferMutationStdinTokenPolicy(context.options, input);
@@ -114,11 +115,14 @@ export function runRuntimeMergeAction(context) {
 export function runRuntimeWorkspaceAction(context) {
     const input = mergedInput(context);
     const subcommand = requiredString(input, "subcommand");
+    if (subcommand === "position") {
+        return readWorkspacePosition(context.global);
+    }
     if (subcommand !== "snapshot") {
         throw createUnknownSubcommandError({
             command_path: "workspace",
             token: subcommand,
-            allowed: ["snapshot"],
+            allowed: ["position", "snapshot"],
             display_name: "workspace",
         });
     }
@@ -171,4 +175,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=8a3a82a1-9e3d-555f-9111-3c3e19887f75
+//# debugId=95e9def9-3f48-5108-8a17-0747fcf64f2d

package/dist/sdk/schema.js

@@ -4,7 +4,7 @@
  * Owns typed schema customization primitives shared by SDK, CLI, and MCP consumers.
  */
 
-!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]="6112923d-5e06-5839-b452-a32818c6398d")}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]="264088a5-09d1-52ed-8b12-af00392e1a5f")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
@@ -422,6 +422,16 @@ export async function runSchemaAddStatus(id, options, global) {
     // --role/--alias preserves metadata defined in settings.schema.statuses, not
     // only what is already in statuses.json.
     const baseDefinition = toExistingStatusDefinition(statusRegistry.by_id.get(normalized.id));
+    const effectiveRoles = normalized.roles ?? baseDefinition?.roles ?? [];
+    if (effectiveRoles.length === 0) {
+        throw new PmCliError(`Status "${normalized.id}" requires at least one lifecycle role. Re-run with --role active, --role blocked, --role draft, or an appropriate terminal/default role.`, EXIT_CODE.USAGE, {
+            code: "status_lifecycle_role_required",
+            examples: [
+                `pm schema add-status "${escapeForDoubleQuotes(normalized.id)}" --role active`,
+                `pm schema add-status "${escapeForDoubleQuotes(normalized.id)}" --role blocked`,
+            ],
+        });
+    }
     const warnings = [];
     const author = resolveAuthor(options.author, settings.author_default);
     const governance = resolveGovernanceKnobs(settings);
@@ -1364,4 +1374,4 @@ export const _testOnlySchemaCommand = {
     workflowSlotsReferencing,
 };
 //# sourceMappingURL=schema.js.map
-//# debugId=6112923d-5e06-5839-b452-a32818c6398d
+//# debugId=264088a5-09d1-52ed-8b12-af00392e1a5f

package/dist/sdk/test/execution.d.ts

@@ -206,6 +206,21 @@ declare function resolveDirectRunnerSubcommand(parsed: {
 } | null): string | undefined;
 declare function firstDirectTestRunnerSubcommand(executable: string, args: string[]): string | undefined;
 declare function segmentInvokesRecursiveTestAll(segment: string): boolean;
+/** Describes the SDK-owned safety policy applied when a linked command is recorded. */
+export interface LinkedTestCommandSafetyClassification {
+    /** Whether intake accepts the command before provenance checks at execution time. */
+    accepted: true;
+    /** Capability-oriented command family, independent of shell wrapping. */
+    command_kind: "direct_runner" | "sandbox_runner" | "other";
+    /** Tracker isolation is injected by the linked-test runtime for every command. */
+    tracker_isolation: "runtime_injected";
+    /** Stored-command provenance and explicit acknowledgment form the execution trust boundary. */
+    trust_boundary: "provenance";
+    /** Human guidance for reproducible execution without presenting string shape as enforcement. */
+    advisory: string;
+}
+/** Classify linked-test commands without pretending string shape is a security boundary. */
+export declare function classifyLinkedTestCommandSafety(command: string): LinkedTestCommandSafetyClassification;
 declare function parseLinkedTestTimeoutSeconds(timeoutSecondsRaw: string | undefined, timeoutAliasRaw: string | undefined): number | undefined;
 declare function parseAddJsonEntries(raw: string[] | undefined): LinkedTest[];
 declare function endLinkedTestProgress(context: LinkedTestProgressContext, executionResult: Pick<LinkedTestExecutionResult, "timedOut" | "maxBufferExceeded" | "outputTruncated" | "exitCode" | "signal">, startedAt: number, mode: LinkedTestProgressMode): void;

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test command surface and its agent-facing runtime behavior.
  */
 
-!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]="de5bc6bf-fe31-5643-a809-ee9ca52aac48")}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]="03f2f710-3b96-5671-85fa-d8ea4726ee86")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm, symlink, } from "node:fs/promises";
@@ -388,14 +388,7 @@ function commandUsesSandboxRunner(normalizedCommand) {
         normalizedCommand.includes("node ./scripts/run-tests.mjs ") ||
         normalizedCommand.endsWith("node ./scripts/run-tests.mjs"));
 }
-function segmentHasExplicitSandboxEnv(normalizedSegment) {
-    const hasExplicitPmPath = /\bpm_path\s*=/.test(normalizedSegment) ||
-        /\$env:pm_path\s*=/.test(normalizedSegment);
-    const hasExplicitPmGlobalPath = /\bpm_global_path\s*=/.test(normalizedSegment) ||
-        /\$env:pm_global_path\s*=/.test(normalizedSegment);
-    return hasExplicitPmPath && hasExplicitPmGlobalPath;
-}
-function segmentInvokesUnsafeDirectTestRunner(normalizedSegment) {
+function segmentInvokesDirectTestRunner(normalizedSegment) {
     const rawTokens = normalizedSegment
         .split(" ")
         .filter((token) => token.length > 0);
@@ -404,45 +397,62 @@ function segmentInvokesUnsafeDirectTestRunner(normalizedSegment) {
         return false;
     }
     const [executable, ...args] = tokens;
+    const shellCommandFlagPattern = SHELL_COMMAND_FLAG_PATTERNS.get(executable);
+    if (shellCommandFlagPattern) {
+        const commandFlagIndex = args.findIndex((argument) => shellCommandFlagPattern.test(argument));
+        return (commandFlagIndex >= 0 &&
+            segmentInvokesDirectTestRunner(args.slice(commandFlagIndex + 1).join(" ")));
+    }
     if (executable === "vitest" ||
         executable.endsWith("/vitest") ||
         executable.endsWith("/vitest.mjs")) {
         return true;
     }
     if (executable === "node") {
-        return nodeArgsInvokeUnsafeDirectTestRunner(args);
+        return nodeArgsInvokeDirectTestRunner(args);
     }
-    return packageManagerInvokesUnsafeDirectTestRunner(executable, args);
+    return packageManagerInvokesDirectTestRunner(executable, args);
 }
-function nodeArgsInvokeUnsafeDirectTestRunner(args) {
+function nodeArgsInvokeDirectTestRunner(args) {
     return (args.includes("--test") ||
         args.some((arg) => arg === "vitest" ||
             arg === "vitest.mjs" ||
             arg.endsWith("/vitest") ||
             arg.endsWith("/vitest.mjs")));
 }
-function packageManagerInvokesUnsafeDirectTestRunner(executable, args) {
+function packageManagerInvokesDirectTestRunner(executable, args) {
     if (executable === "npx" || executable === "bunx") {
         return isDirectTestRunnerSubcommand(parseNpxCommand(args)?.command);
     }
     if (executable === "pnpm" || executable === "npm") {
         return (isDirectTestRunnerSubcommand((executable === "pnpm"
             ? parsePnpmDlxCommand(args)
-            : parseNpmExecCommand(args))?.command) || firstDirectTestRunnerSubcommand(executable, args) === "vitest");
+            : parseNpmExecCommand(args))?.command) ||
+            isDirectTestRunnerSubcommand(firstDirectTestRunnerSubcommand(executable, args)));
     }
     return ((executable === "yarn" || executable === "bun") &&
-        firstDirectTestRunnerSubcommand(executable, args) === "vitest");
+        isDirectTestRunnerSubcommand(firstDirectTestRunnerSubcommand(executable, args)));
 }
-function assertSandboxSafeTestRunnerCommand(command) {
+/** Classify linked-test commands without pretending string shape is a security boundary. */
+export function classifyLinkedTestCommandSafety(command) {
     const normalized = normalizeCommandForValidation(command);
     const segments = splitNormalizedCommandSegments(normalized);
-    const hasUnsafeDirectRunnerSegment = segments.some((segment) => !commandUsesSandboxRunner(segment) &&
-        segmentInvokesUnsafeDirectTestRunner(segment) &&
-        !segmentHasExplicitSandboxEnv(segment));
-    if (!hasUnsafeDirectRunnerSegment) {
-        return;
-    }
-    throw new PmCliError('Linked test runner commands must be sandbox-safe: use "node scripts/run-tests.mjs <test|coverage>", use a package-manager script such as "pnpm test", or include PM_PATH=... PM_GLOBAL_PATH=... INLINE in the command string (exporting them in your shell environment is not checked). Example: "PM_PATH=/tmp/pm-x PM_GLOBAL_PATH=/tmp/pm-x-g vitest run".', EXIT_CODE.USAGE);
+    const directRunner = segments.some((segment) => !commandUsesSandboxRunner(segment) &&
+        segmentInvokesDirectTestRunner(segment));
+    const sandboxRunner = segments.some(commandUsesSandboxRunner);
+    return {
+        accepted: true,
+        command_kind: directRunner
+            ? "direct_runner"
+            : sandboxRunner
+                ? "sandbox_runner"
+                : "other",
+        tracker_isolation: "runtime_injected",
+        trust_boundary: "provenance",
+        advisory: directRunner
+            ? "Accepted with runtime-injected tracker isolation. Prefer the repository sandbox runner when available for reproducible build and coverage setup."
+            : "Accepted with runtime-injected tracker isolation and provenance checks before execution.",
+    };
 }
 function getRuntimeSafetySkipReason(command) {
     if (!invokesRecursiveTestAllCommand(command))
@@ -464,7 +474,6 @@ function parseAddEntry(entry) {
         throw new PmCliError("--add requires command=<value> or a bare command (path=<value> is optional metadata)", EXIT_CODE.USAGE);
     }
     assertNoRecursiveTestAllCommand(command);
-    assertSandboxSafeTestRunnerCommand(command);
     return {
         command,
         path: trimLinkedTestEntryField(kv.path),
@@ -516,7 +525,6 @@ function parseAddJsonEntries(raw) {
                 throw new PmCliError("--add-json requires a non-empty command string", EXIT_CODE.USAGE);
             }
             assertNoRecursiveTestAllCommand(command);
-            assertSandboxSafeTestRunnerCommand(command);
         }
         return parsed;
     });
@@ -1325,7 +1333,7 @@ function commandUsesTestNameFilter(command) {
         return true;
     }
     return splitNormalizedCommandSegments(normalized).some((segment) => /(?:^|\s)-t(?:=|\s)/u.test(segment) &&
-        segmentInvokesUnsafeDirectTestRunner(segment));
+        segmentInvokesDirectTestRunner(segment));
 }
 function createLinkedTestSandboxLayout(sandboxRoot) {
     return {
@@ -2201,4 +2209,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=de5bc6bf-fe31-5643-a809-ee9ca52aac48
+//# debugId=03f2f710-3b96-5671-85fa-d8ea4726ee86

package/docs/AGENT_GUIDE.md

@@ -12,7 +12,7 @@ pm search "<request keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
 pm init --agent-guidance status
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide workflows
 ```
 

package/docs/AGENT_PROVENANCE_ADR.md

@@ -84,7 +84,7 @@ Modern MCP clients may supply a bounded
 `io.modelcontextprotocol/clientInfo.provenance` map in each request's `_meta`.
 The server retains only valid dimension names and trimmed values, then resolves
 that map inside the invocation-scoped identity context for that request. The
-bounded `2025-06-18` adapter accepts the same map during legacy `initialize`.
+bounded initialize-era adapter accepts the same map during legacy `initialize`.
 A missing MCP signal is recorded as explicit `null`; it is never confused with
 a legacy entry that predates the dimension.
 

package/docs/AGENT_RUNTIME_PRIMITIVES.md

@@ -158,8 +158,8 @@ summary. No history entry is rewritten.
 
 MCP 2026-07-28 reads `io.modelcontextprotocol/clientInfo` independently from
 every request's `_meta` and scopes only that request to the client signal. The
-bounded legacy adapter still reads `clientInfo` during `2025-06-18`
-`initialize`. Optional host-provided `model`, `session`, `provenance`, and
+bounded legacy adapter still reads `clientInfo` during an initialize-era
+handshake. Optional host-provided `model`, `session`, `provenance`, and
 `episode` fields are supported, but version is not misclassified as a model or
 session. Provenance keys must use the bounded
 lowercase dimension vocabulary; blank, malformed, and oversized data is

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -134,8 +134,8 @@ pnpm smoke:codex-plugin
 ```bash
 pm contracts --schema-only --json
 pm contracts --command extension --flags-only --json
-pm extension --doctor --project --detail summary --strict-exit
-pm extension --reload --project
+pm package doctor --project --detail summary --strict-exit
+pm package reload --project
 ```
 
 Why this matters:
@@ -188,7 +188,7 @@ The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.jso
 
 The MCP server uses JSON-RPC 2.0 over stdio with canonical protocol version
 `2026-07-28`. A bounded legacy path remains for unversioned older hosts, with
-`2025-06-18` initialize available to enrich client identity; current hosts
+initialize-era handshakes available to enrich client identity; current hosts
 discover the server and send metadata on every request.
 
 ## Extension Policy Diagnostics

package/docs/COMMANDS.md

@@ -67,7 +67,7 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 | Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                                    | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
 | Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                                            | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
 
-`†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm install linked-test-adapters --project`).
+`†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm package install linked-test-adapters --project`).
 
 ## Bootstrap
 
@@ -113,21 +113,21 @@ Use `--with-packages` for one-step agent setup when bundled package commands sho
 
 ```bash
 pm package                     # bare command defaults to --explore (list installed)
-pm install '*' --project
+pm package install '*' --project
 pm package catalog --project
 pm package manage --project --output-format json
-pm install npm:@scope/pm-package --project
+pm package install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
 pm package doctor --project --detail summary
 pm package migrate --project --dry-run --json
 pm package migrate --project --json
-pm upgrade --dry-run
-pm upgrade --packages-only
-pm upgrade --cli-only --repair
+pm package upgrade --dry-run
+pm package upgrade --packages-only
+pm package upgrade --cli-only --repair
 ```
 
-`pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+`pm package` is the canonical package-first workflow. `pm package` and the hidden `pm extension` alias default to `--explore` on a bare invocation so agents can list installed packages without remembering an action flag. `pm package install '*'`, shell-expanded `pm package install *`, and `pm package install all` install bundled first-party packages. `pm install`, `pm upgrade`, and `pm extension` remain executable as deprecated compatibility spellings declared in `PM_COMMAND_ALIAS_CONTRACTS`; they emit a migration hint and must not appear in documentation or skills as instructions.
 `pm package catalog` emits one row per package, with every resolvable bundled
 alias preserved in `aliases`; totals therefore measure packages rather than
 alias-index entries. `pm package manage` participates in the universal read
@@ -141,7 +141,7 @@ the choice ambiguous and provides explicit bare and `npm:` retry commands.
 durable workspace-history receipts; a successful migration is skipped on later
 processes, while a failed migration remains retryable. `extension migrate` is
 the compatibility spelling.
-When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
+When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm package install calendar`, `pm package install search-advanced`, `pm package install governance-audit`, or `pm package install guide-shell`).
 
 ## Triage
 
@@ -669,7 +669,7 @@ Tracker references: [pm-72xf](../.agents/pm/features/pm-72xf.toon).
 
 ## Templates
 
-After `pm install templates --project`, `pm templates` lists both saved templates and built-in starters:
+After `pm package install templates --project`, `pm templates` lists both saved templates and built-in starters:
 
 ```bash
 pm templates
@@ -804,7 +804,7 @@ pm test <id> --run --only-last
 pm test-all --status in_progress --progress
 ```
 
-Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` for repo-local test suites; normal package-manager scripts such as `pnpm test` and `npm run test` are accepted because linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH`. Direct runner binaries such as `vitest` or `node --test` still need the wrapper or explicit inline sandbox env. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. Linked tests retain append order; consequently `--only-last` always selects the most recently added stored test. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
+Linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH` for every command and checks stored-command provenance before process creation. Direct runner binaries such as `vitest` or `node --test`, shell-wrapped equivalents, package-manager scripts, and non-Node runners are accepted consistently; prefer `node scripts/run-tests.mjs ...` when available because it also reproduces repository build, coverage, and cleanup policy. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. Linked tests retain append order; consequently `--only-last` always selects the most recently added stored test. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
 
 Strict linked-test guards:
 
@@ -818,7 +818,7 @@ pm test <id> --run \
 
 ## Search Reindex and Eval
 
-`reindex` is provided by the `search-advanced` package (`pm install search-advanced --project`).
+`reindex` is provided by the `search-advanced` package (`pm package install search-advanced --project`).
 
 ```bash
 pm reindex --mode keyword
@@ -1240,7 +1240,7 @@ only after selecting the exact path.
 
 ## Completion
 
-`pm completion` is provided by the optional `guide-shell` package (`pm install guide-shell --project`).
+`pm completion` is provided by the optional `guide-shell` package (`pm package install guide-shell --project`).
 
 ```bash
 pm completion bash

package/docs/CONFIGURATION.md

@@ -210,7 +210,7 @@ Markdown item files are treated as legacy migration input only. Mutations always
 Most commands default to sparse TOON:
 
 ```bash
-pm list-open --limit 10
+pm list --status open --limit 10
 ```
 
 Use JSON for strict machine parsing:

package/docs/DEFECT_RECURRENCE.md

@@ -79,6 +79,8 @@ The repository example is [config/defect-recurrence-policy.json](../config/defec
 
 Repository policy validation rejects duplicate ids, absent historical examples, missing family negative controls, invalid taxonomy values, and budgets outside zero through one. Deterministic sorting makes the serialized policy merge-friendly.
 
+Register a family whenever a defect is recorded as a recurrence of an earlier one, meaning the new item carries a `recurs_from` edge to its predecessor. A recurrence with no family produces no local and no hosted protection, so the next instance is rediscovered by hand. Coverage of recorded recurrence lineages is not yet computed by any gate; that gap is tracked on [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon).
+
 ## Defect Evidence on PM Items
 
 Projects can register the structured fields without changing the SDK:

package/docs/MCP_2026_07_28.md

@@ -41,13 +41,33 @@ request.
 
 ## Legacy boundary
 
-The sole supported legacy revision is `2025-06-18`, accepted through the
-existing stdio adapter. Unversioned requests stay on this legacy path because
-they cannot claim the current revision; `initialize` enriches their client
-identity but is not required for compatibility with older pm hosts. The
-adapter has no session id, does not affect modern requests, and is excluded
-from `server/discover`'s `supportedVersions` because it cannot be selected
-through modern per-request metadata.
+Legacy means every revision that establishes a session with an `initialize`
+handshake, which the canonical revision defines as `2025-11-25` and earlier.
+The stdio adapter therefore accepts the full initialize-era set, newest first:
+
+| Revision | Accepted at `initialize` | Notes |
+|----------|--------------------------|-------|
+| `2025-11-25` | yes | Final legacy revision; offered when a client omits `protocolVersion` |
+| `2025-06-18` | yes | Earlier legacy revision retained for existing consumers |
+
+`initialize` answers with the revision the client requested, because a legacy
+client has no fall-forward mechanism and treats the answered version as the
+negotiated one. A revision outside the set is refused with `-32022` and the
+refusal names every supported revision, since that error text is the only
+diagnostic such a client can surface.
+
+`PM_MCP_LEGACY_PROTOCOL_VERSIONS` on the public SDK surface is the single
+declaration of this set. The plugin MCP smoke gate reads it from the built SDK
+and drives one real `initialize` per declared revision against the released
+launcher, plus a negative control for an undeclared revision, so the accepted
+set and the documented set cannot drift apart.
+
+Unversioned requests stay on this legacy path because they cannot claim the
+current revision; `initialize` enriches their client identity but is not
+required for compatibility with older pm hosts. The adapter has no session id,
+does not affect modern requests, and is excluded from `server/discover`'s
+`supportedVersions` because it cannot be selected through modern per-request
+metadata.
 
 The adapter is scheduled for removal only after published-client telemetry and
 release probes show no required legacy consumers for two consecutive release
@@ -58,7 +78,7 @@ windows. Removal is a reviewed compatibility change, never a history rewrite.
 - Stdio modern clients call `server/discover` with current request metadata,
   then send the same version and capability keys on every request.
 - Stdio legacy clients retain their existing response shapes and may use
-  `initialize` with `2025-06-18` to supply client identity.
+  `initialize` with any accepted legacy revision to supply client identity.
 - Streamable HTTP requires `MCP-Protocol-Version` and `Mcp-Method` on every
   request. `Mcp-Name` is required only for `prompts/get`, `resources/read`, and
   `tools/call`; other methods omit it. Schema-declared `x-mcp-header` values are

package/docs/MCP_2026_07_28_CONFORMANCE.md

@@ -13,6 +13,7 @@ evidence or an explicit open obligation.
 | Header mismatch `-32020` and missing capability `-32021`                                           | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented in SDK, stdio, and Streamable HTTP                                                                            | SDK negative controls and `tests/integration/mcp-streamable-http.spec.ts`                 |
 | Required result `resultType`; legacy omission means complete only at compatibility boundary        | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented for modern pm results                                                                                        | SDK unit and modern direct-server tests                                                   |
 | No modern initialize, initialized notification, ping, or protocol session                          | [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon) | Implemented with bounded legacy stdio adapter                                                                            | modern removed-method and legacy handshake tests                                          |
+| Legacy interoperability covers every initialize-era revision the spec names   | [pm-edywqn](../.agents/pm/issues/pm-edywqn.toon)   | Implemented: `2025-11-25` and `2025-06-18` accepted, requested revision echoed                                            | `tests/integration/mcp-handshake.spec.ts` handshake matrix plus the plugin smoke `assertProtocolHandshakeMatrix` real-process gate and its negative control |
 | MRTR `input_required`, retry state, and reverse-request removal                                    | [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon)  | Implemented for SDK and stateless stdio adapter                                                                          | `tests/unit/sdk/mcp/interactions.spec.ts`; direct server negative controls                |
 | `subscriptions/listen`, request-scoped streams, no SSE resumability                                | [pm-v7e337](../.agents/pm/features/pm-v7e337.toon)  | Implemented locally; packed and published proof follows merge                                                            | subscription SDK, stdio, HTTP, backpressure, disconnect, and retry tests                  |
 | Official `io.modelcontextprotocol/tasks` extension                                                 | [pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon)  | Implemented for eligible tool calls, durable lifecycle, and stdio methods; notifications remain with subscriptions owner | `tests/unit/sdk/mcp/tasks.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |

package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md

@@ -7,7 +7,7 @@ Tracker references: [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
 pm exposes the same MCP 2026-07-28 dispatcher through two adapters:
 
 - `pm-mcp` is the local JSON-RPC/stdio process. It retains a bounded
-  `2025-06-18` compatibility adapter for existing local consumers.
+  initialize-era compatibility adapter for existing local consumers.
 - `pm-mcp-http` is the canonical sessionless Streamable HTTP POST process. It
   accepts only modern request-local protocol metadata and never creates an
   MCP session.
@@ -155,7 +155,9 @@ an unlisted source path cannot create that exemption. Any canonical match for a
 removed method, session header, SSE resume mechanism, legacy
 resource-subscription method, or deprecated server policy fails the gate.
 
-The compatibility adapter supports only protocol `2025-06-18` on local stdio.
+The compatibility adapter supports the initialize-era revisions declared by
+`PM_MCP_LEGACY_PROTOCOL_VERSIONS` (`2025-11-25` and `2025-06-18`) on local
+stdio.
 It may be removed after telemetry and installed-consumer probes show no
 required legacy clients for two consecutive release windows. Deprecated
 2026-07-28 fields remain available only where the normative registry requires

package/docs/ONBOARDING.md

@@ -43,7 +43,7 @@ pm context --limit 10
 pm search "<request keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide workflows
 ```
 

package/docs/README.md

@@ -7,7 +7,7 @@ This directory is the public documentation home for `pm-cli`. It is organized fo
 `pm guide` is provided by the optional `guide-shell` package. Install it when local in-CLI documentation routing is useful:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide
 pm guide quickstart
 pm guide commands --depth standard
@@ -72,6 +72,7 @@ pm guide release --json
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context and Evidence Contracts](SDK_CONTEXT_EVIDENCE_CONTRACTS.md) - material omission receipts, scoped preflight activation, truthful merge preference, claim-race classification, and versioned history hashes.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
+- [Workspace Position and Lifecycle Roles](WORKSPACE_POSITION_AND_LIFECYCLE.md) - role-safe custom workflows plus one bounded merge-fence, receipt, history-drift, and next-action SDK read.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -144,7 +144,7 @@ consumer therefore cannot interpret the missing command or action arrays as a
 successful empty contract.
 
 ```bash
-pm list-open --output-include id,title,status --output-limit 10
+pm list --status open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
 pm search "runtime contracts" --output-limit 5 --output-format json
 pm stats --output-row-contract

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -129,7 +129,7 @@ pm reindex --mode hybrid
 If the command is absent, recovery is a two-step executable sequence:
 
 ```bash
-pm install search-advanced --project
+pm package install search-advanced --project
 pm reindex --mode hybrid
 ```