Guard pm tracker path targeting for agents

.agents/pm/plans/pm-xm98.toon

@@ -0,0 +1,23 @@
+id: pm-xm98
+title: 2026-06-07 pm CLI ecosystem audit lanes
+description: "pm-yo3f: CLI/SDK/package/GitHub/observability audit with sub-agent lanes"
+type: Plan
+status: closed
+priority: 2
+tags: []
+created_at: "2026-06-07T08:15:48.718Z"
+updated_at: "2026-06-07T08:58:36.477Z"
+author: codex-broad-ecosystem-audit-20260607
+resolution: Completed and closed all audit plan lanes with evidence recorded on pm-yo3f.
+expected_result: All delegated audit lanes complete with tracker evidence and no open plan steps.
+actual_result: All four plan steps completed and pm-xm98 was closed/released after integration.
+close_reason: "Audit lane plan completed: all four sub-agent lanes completed with evidence on pm-yo3f; implementation and verification integrated by main agent."
+plan_mode: approved
+plan_scope: "pm-yo3f: CLI/SDK/package/GitHub/observability audit with sub-agent lanes"
+plan_harness: codex
+plan_steps[4]{id,order,title,status,created_at,updated_at,body,evidence,completed_at}:
+  plan-step-001,1,External package temp-project smoke,completed,"2026-06-07T08:15:58.680Z","2026-06-07T08:41:55.384Z","Discover current external pm packages, smoke install in temporary projects, and record compatibility or package-author SDK gaps on pm-yo3f.","External package smoke sub-agent: pnpm build passed; discovered 17 current npm packages via pnpm smoke:external-packages -- --discover-only --limit 25; full smoke pnpm smoke:external-packages -- --limit 25 --timeout-ms 180000 completed ok=true tested=17 failed=0 with install/doctor/contracts for all packages; project pm-changelog doctor clean and changelog actions invocable. Non-blocking doctor warnings observed in successful full run: pm-todos extension_command_handler_collision; pm-ts-starter and pm-starter output renderer/service override warnings. Duplicate focused rerun later timed out during installs under concurrent smoke/changelog processes, treated as environmental contention not compatibility failure.","2026-06-07T08:41:55.384Z"
+  plan-step-002,2,SDK and extension API review,completed,"2026-06-07T08:15:58.909Z","2026-06-07T08:22:52.837Z","Review public SDK exports, testing helpers, package creation ergonomics, and type-safety surfaces; record actionable findings on pm-yo3f.","SDK/API review complete. Evidence recorded on pm-yo3f by codex-sdk-review-20260607: SDK/package docs and tests reviewed; focused SDK/package tests passed (5 files, 73 tests); temp package-author smoke passed; findings are stale contracts snapshot missing init --force and low-risk package scaffold comment/docs-code mismatch around defineExtension vs import-free scaffold.","2026-06-07T08:22:52.837Z"
+  plan-step-003,3,Agent output and docs progressive-disclosure review,completed,"2026-06-07T08:15:59.143Z","2026-06-07T08:19:36.730Z","Review token-efficient CLI output, README/docs progressive disclosure, duplicated/legacy docs, and agent UX; record findings on pm-yo3f.","Docs/agent-UX review complete. Reviewed README, AGENTS, COMMANDS, CONFIGURATION, TESTING, EXTENSIONS, SDK. Removed duplicate registry-404 fallback paragraph in docs/EXTENSIONS.md, linked doc/test evidence to pm-yo3f, and verified with pm test pm-yo3f --run --progress (pnpm build + pnpm quality:docs-links passed).","2026-06-07T08:19:36.730Z"
+  plan-step-004,4,GitHub CI security observability review,completed,"2026-06-07T08:15:59.359Z","2026-06-07T08:24:00.589Z",Review gh issue/PR/check/security surfaces plus Sentry/telemetry gates; record findings on pm-yo3f.,"GitHub/observability sub-agent complete: no open PRs; issue #140 in scope; latest main CI red on changelog:pm:check stale CHANGELOG.md; CodeQL and Nightly green; pnpm audit/security scan clean; Sentry/telemetry gate passed with critical=0 high=0 telemetry error rate=2.07 missing rows=0; telemetry stack healthy with queue=0 consumers=1 and 17099 events/24h; local release-gate subset red due concurrent --path/--pm-path tests, no source files edited by this lane.","2026-06-07T08:24:00.589Z"
+body: ""

AGENTS.md

@@ -54,7 +54,7 @@ export PM_AUTHOR=<stable-agent-id>
 
 Use `PM_CMD=pm` only after `pm` clearly resolves to this checkout's current build. Otherwise run `node dist/cli.js` from the repository root.
 
-For real repository tracking, do not override `PM_PATH`. For tests and dogfood runs, use sandboxed `PM_PATH` and `PM_GLOBAL_PATH`; prefer `node scripts/run-tests.mjs ...` because it sets them automatically.
+For real repository tracking, do not override `PM_PATH`. If a script must target a tracker explicitly, prefer `--pm-path <repo>/.agents/pm`; `--path` is only a backward-compatible tracker-root alias, not a workspace/cwd flag. For tests and dogfood runs, use sandboxed `PM_PATH` and `PM_GLOBAL_PATH`; prefer `node scripts/run-tests.mjs ...` because it sets them automatically.
 
 <!-- pm-cli:agent-guidance:start:v1 -->
 ## pm Workflow Quickstart

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Add schema show-status status inspection ([pm-qpus](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-qpus.toon))
+
+### Other
+
+- 2026-06-07 agent UX package ecosystem and path guardrail hardening ([pm-yo3f](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yo3f.toon))
+- 2026-06-07 pm CLI ecosystem audit lanes ([pm-xm98](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/plans/pm-xm98.toon))
+
 ## 2026.6.7 - 2026-06-07
 
 ### Added

docs/CONFIGURATION.md

@@ -5,6 +5,7 @@
 ## Agent Quick Context
 
 - Do not override `PM_PATH` for real repository tracking.
+- Prefer `--pm-path <repo>/.agents/pm` when a script must target tracker storage explicitly; `--path` remains a compatibility alias and is not a workspace/cwd flag.
 - Do set `PM_AUTHOR` for maintainer and agent mutations.
 - Use `--json` only when strict parsing is needed.
 - Use `pm contracts` for current command/schema metadata.
@@ -82,6 +83,11 @@ Runtime item types are context primitives. Use `pm schema list` to inspect the m
 | `PM_OLLAMA_MODEL` | choose default Ollama embedding model |
 | `PM_DISABLE_OLLAMA_AUTO_DEFAULTS` | disable implicit Ollama search defaults |
 
+For command-level tracker targeting, prefer `--pm-path <tracker-root>`. The old
+`--path` flag is still accepted, but it means the pm tracker storage directory
+itself, not the repository workspace. During `pm init`, explicit tracker paths
+that look like workspace roots are rejected unless `--force` is provided.
+
 Tests should set both `PM_PATH` and `PM_GLOBAL_PATH` to temporary directories. The wrapper `node scripts/run-tests.mjs ...` does that automatically.
 
 ## Item Storage Format

docs/EXTENSIONS.md

@@ -50,11 +50,6 @@ pm package doctor --project --detail deep --trace
 pm github validate --repo owner/repo
 ```
 
-If `npm:<name>` returns a registry 404, JSON error output includes a compact
-recovery bundle with `fallback_candidates` and `next_best_command`. For
-unpublished first-party packages, the first fallback is the canonical GitHub
-source, for example `pm install --project github.com/unbraind/<name>`.
-
 For `pm-github`, run `pm github validate --repo owner/repo` before mutating commands; write paths require `GITHUB_TOKEN`/`GH_TOKEN` or `gh auth login`.
 
 For ecosystem maintenance, use the reusable external package smoke harness after

src/cli/bootstrap-args.ts

@@ -4,32 +4,41 @@ import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 function parseBootstrapPathToken(
   token: string,
   next: string | undefined,
-): { consumed: number; pathValue?: string } | null {
-  if (token === "--path") {
+): { consumed: number; pathValue?: string; preferred: boolean } | null {
+  if (token === "--path" || token === "--pm-path") {
     if (typeof next === "string" && next.length > 0) {
       return {
         consumed: 2,
         pathValue: next,
+        preferred: token === "--pm-path",
       };
     }
     return {
       consumed: 1,
+      preferred: token === "--pm-path",
     };
   }
 
-  if (!token.startsWith("--path=")) {
+  const inlinePrefix = token.startsWith("--path=")
+    ? "--path="
+    : token.startsWith("--pm-path=")
+      ? "--pm-path="
+      : undefined;
+  if (!inlinePrefix) {
     return null;
   }
 
-  const value = token.slice("--path=".length);
+  const value = token.slice(inlinePrefix.length);
   if (value.length > 0) {
     return {
       consumed: 1,
       pathValue: value,
+      preferred: inlinePrefix === "--pm-path=",
     };
   }
   return {
     consumed: 1,
+    preferred: inlinePrefix === "--pm-path=",
   };
 }
 
@@ -42,7 +51,8 @@ export interface BootstrapGlobalOptions {
 }
 
 export function parseBootstrapGlobalOptions(argv: string[]): BootstrapGlobalOptions {
-  let pathValue: string | undefined;
+  let legacyPathValue: string | undefined;
+  let pmPathValue: string | undefined;
   let noExtensions = false;
   let noPager = false;
   let json = false;
@@ -76,15 +86,19 @@ export function parseBootstrapGlobalOptions(argv: string[]): BootstrapGlobalOpti
     const parsedPath = parseBootstrapPathToken(token, argv[index + 1]);
     if (parsedPath) {
       if (parsedPath.pathValue !== undefined) {
-        pathValue = parsedPath.pathValue;
+        if (parsedPath.preferred) {
+          pmPathValue = parsedPath.pathValue;
+        } else {
+          legacyPathValue = parsedPath.pathValue;
+        }
       }
       index += parsedPath.consumed;
       continue;
     }
     index += 1;
   }
   return {
-    path: pathValue,
+    path: pmPathValue ?? legacyPathValue,
     noExtensions,
     noPager,
     json,
@@ -111,11 +125,11 @@ export function stripGlobalBootstrapTokens(argv: string[]): string[] {
       index += 1;
       continue;
     }
-    if (token === "--path") {
+    if (token === "--path" || token === "--pm-path") {
       index += 2;
       continue;
     }
-    if (token.startsWith("--path=")) {
+    if (token.startsWith("--path=") || token.startsWith("--pm-path=")) {
       index += 1;
       continue;
     }
@@ -182,12 +196,13 @@ function findCommandTokenIndex(argv: string[]): number | undefined {
     if (token === "--") {
       return undefined;
     }
-    if (token === "--path") {
+    if (token === "--path" || token === "--pm-path") {
       index += 1;
       continue;
     }
     if (
       token.startsWith("--path=") ||
+      token.startsWith("--pm-path=") ||
       token === "--json" ||
       token === "--quiet" ||
       token === "--no-extensions" ||
@@ -538,9 +553,10 @@ function normalizeLongOptionToken(
 
 // Global option flags whose value may legitimately begin with "--" (commander
 // accepts such values). Their value token must not be reinterpreted as a list
-// flag during coalescing. `--path <dir>` is the documented case; other globals
+// flag during coalescing. `--pm-path <dir>` and its legacy `--path <dir>`
+// alias are the documented cases; other globals
 // (--json/--quiet/--no-extensions/--no-pager/--profile) are boolean.
-const GLOBAL_VALUE_CONSUMING_FLAGS = new Set<string>(["--path"]);
+const GLOBAL_VALUE_CONSUMING_FLAGS = new Set<string>(["--pm-path", "--path"]);
 
 function splitCanonicalListToken(token: string): { flag: string; inlineValue?: string } | null {
   if (!token.startsWith("--")) {