@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/core/store/item-store.js

@@ -4,8 +4,9 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="bffd3114-3e85-58ae-90c7-eea5069cdb89")}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]="7cbc256e-cdd8-51de-9c22-08cf2f3cd010")}catch(e){}}();
 import fs from "node:fs/promises";
+import { recordItemMetadataEnumeration } from "./item-metadata-read-work.js";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../extensions/item-fields.js";
@@ -18,6 +19,7 @@ import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "..
 import { resolveItemTypeRegistry } from "../item/type-registry.js";
 import { acquireLock } from "../lock/lock.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
+import { isUtf8 } from "node:buffer";
 import { normalizeItemId, normalizeRawItemId } from "../item/id.js";
 import { acquireItemMetadataDerivedIndexLock, listAllDocumentCandidatesCached, listAllDocumentsCached, listAllDocumentsCachedLight, refreshItemMetadataDerivedIndex, } from "./item-metadata-cache.js";
 import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS } from "./paths.js";
@@ -96,23 +98,61 @@ export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredForma
 }
 /** Implements read located item for the public runtime surface of this module. */
 export async function readLocatedItem(item, options = {}) {
-    const raw = await fs.readFile(item.itemPath, "utf8");
+    const snapshot = await readLocatedItemSnapshot(item, options);
+    if (snapshot.error !== null)
+        throw snapshot.error;
+    return { raw: snapshot.raw, document: snapshot.document };
+}
+/**
+ * Read once and retain a recoverable parse failure beside its exact text snapshot.
+ * Filesystem and merge-conflict errors still throw; callers must explicitly
+ * reconstruct an invalid document before performing any mutation.
+ */
+export async function readLocatedItemSnapshot(item, options = {}) {
+    const bytes = await fs.readFile(item.itemPath);
+    if (!isUtf8(bytes)) {
+        throw new PmCliError("Item contains invalid UTF-8; preserve a binary backup before recovering it.", EXIT_CODE.CONFLICT, { code: "item_document_encoding_invalid", item_id: item.id, item_path: item.itemPath, byte_length: bytes.length, empty: false });
+    }
+    const raw = bytes.toString("utf8");
     await runActiveOnReadHooks({
         path: item.itemPath,
         scope: "project",
     });
-    const document = parseItemDocument(raw, {
-        format: item.item_format,
-        schema: options.schema,
-        extensionFieldNames: resolveActiveExtensionFieldNames(options.extensionFieldNames),
-        onWarning: (warning) => appendWarning(options.warnings, warning),
-    });
-    return { raw, document };
+    let document;
+    try {
+        document = parseItemDocument(raw, {
+            format: item.item_format,
+            schema: options.schema,
+            extensionFieldNames: resolveActiveExtensionFieldNames(options.extensionFieldNames),
+            onWarning: (warning) => appendWarning(options.warnings, warning),
+        });
+    }
+    catch (error) {
+        if (error instanceof PmCliError && error.code === "item_document_invalid") {
+            return {
+                raw,
+                document: null,
+                error: new PmCliError(`Cannot read ${item.id} at ${item.itemPath}${bytes.length === 0 ? " (zero-length file)" : ""}: ${error.message}`, error.exitCode, {
+                    ...error.context,
+                    item_id: item.id,
+                    item_path: item.itemPath,
+                    byte_length: bytes.length,
+                    empty: bytes.length === 0,
+                    nextSteps: [
+                        `Run pm history ${item.id} --full, then pm restore ${item.id} <version> to recover a recorded state.`,
+                    ],
+                }),
+            };
+        }
+        throw error;
+    }
+    return { raw, document, error: null };
 }
 /** Implements list all item metadata for the public runtime surface of this module. */
 export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
     await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCached(pmRoot, preferredFormat, typeToFolder, warnings, schema);
+    recordItemMetadataEnumeration(documents.length);
     return documents.map((document) => document.metadata);
 }
 /**
@@ -124,6 +164,7 @@ export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder
 export async function listAllItemMetadataLight(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
     await assertReadableTrackerRoot(pmRoot);
     const documents = await listAllDocumentsCachedLight(pmRoot, preferredFormat, typeToFolder, warnings, schema);
+    recordItemMetadataEnumeration(documents.length);
     return documents.map((document) => document.metadata);
 }
 /** List item metadata with bodies, optionally bypassing the derived-index fast path when an integrity workflow must re-read authoritative files. */
@@ -133,6 +174,7 @@ export async function listAllItemMetadataWithBody(pmRoot, preferredFormat, typeT
         includeBody: true,
         forceSourceScan: options.forceSourceScan,
     });
+    recordItemMetadataEnumeration(candidates.length);
     return candidates.map((candidate) => ({
         ...candidate.metadata,
         // includeBody:true guarantees candidate bodies are materialized.
@@ -649,4 +691,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=bffd3114-3e85-58ae-90c7-eea5069cdb89
+//# debugId=7cbc256e-cdd8-51de-9c22-08cf2f3cd010

package/dist/core/store/settings-validator.js

@@ -12,7 +12,7 @@
  * byte-identical to the previous implementation.
  */
 
-!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]="0e135793-d2ed-505b-b73e-6db55218d8af")}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]="c9cac741-16ba-5466-806f-bf8881a2ffa2")}catch(e){}}();
 import { GOVERNANCE_PRESET_VALUES, RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, RUNTIME_STATUS_ROLE_VALUES, RUNTIME_UNKNOWN_FIELD_POLICY_VALUES, } from "../../types.js";
 // Generic over `never` so it is assignable to every `Outcome<T>`.
 const FAIL = { ok: false };
@@ -137,6 +137,7 @@ const itemTypeDefinition = vObject({
     // Per-type create-time default status (config-driven); preserved so inline
     // settings.item_types.definitions behave identically to schema/types.json.
     default_status: vOptional(vString),
+    execution_role: vOptional(vLiteral("agent", "human", "gate")),
     folder: vOptional(vString),
     aliases: vOptional(vArray(vString)),
     required_create_fields: vOptional(vArray(vString)),
@@ -418,4 +419,4 @@ export function validateSettings(raw) {
     return { success: true, data: result.value };
 }
 //# sourceMappingURL=settings-validator.js.map
-//# debugId=0e135793-d2ed-505b-b73e-6db55218d8af
+//# debugId=c9cac741-16ba-5466-806f-bf8881a2ffa2

package/dist/core/validate/fix-planning.d.ts

@@ -97,7 +97,7 @@ export interface StaleLinkPruneRow {
     /** Value that configures or reports link kind for this contract. */
     link_kind: "files" | "docs";
     /** Value that configures or reports classification for this contract. */
-    classification: "moved" | "deleted";
+    classification: "moved" | "deleted" | "malformed";
 }
 /** Plan link prunes for `--prune-missing` (pm-0v2m / GH-184). Only links whose stale path classified as `deleted` are pruned; `moved` links keep their relink candidates in the files-check details instead of being dropped, so recoverable link information is never destroyed. Link removal only — real files are never touched. */
 export declare function planStaleLinkPruneFixes(rows: readonly StaleLinkPruneRow[]): ValidateFixRecord[];

package/dist/core/validate/fix-planning.js

@@ -16,7 +16,7 @@
  *   explicitly granted.
  */
 
-!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]="ab236f47-a866-5236-b8da-f7f23140b978")}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]="98a73818-c4ef-5bce-8b23-6c40f7312cc3")}catch(e){}}();
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
 import { resolveEstimateDefaultMinutes } from "./estimate-defaults.js";
@@ -187,4 +187,4 @@ export function toFixOutputRow(fix) {
     };
 }
 //# sourceMappingURL=fix-planning.js.map
-//# debugId=ab236f47-a866-5236-b8da-f7f23140b978
+//# debugId=98a73818-c4ef-5bce-8b23-6c40f7312cc3

package/dist/core/validate/missing-link-owners.d.ts

@@ -13,7 +13,7 @@
  * the already-collected stale-link rows plus a metadata `lookup` closure.
  */
 /** Classification assigned to a stale linked path during files validation. */
-export type StaleLinkClassification = "moved" | "deleted";
+export type StaleLinkClassification = "moved" | "deleted" | "malformed";
 /** Documents the stale link owner input payload exchanged by command, SDK, and package integrations. */
 export interface StaleLinkOwnerInput {
     /** Value that configures or reports item id for this contract. */

package/dist/core/validate/missing-link-owners.js

@@ -12,10 +12,12 @@
  * Pure module (GH-210): no filesystem access and no heavy imports — callers pass
  * the already-collected stale-link rows plus a metadata `lookup` closure.
  */
-/** `moved` wins over `deleted` when a single path's rows disagree on classification: `moved` means a relink candidate exists, which is the safer, more-actionable signal (relink instead of risk pruning a still-reachable link). In practice all rows for one path share a classification; this is a deterministic tie-break for the degenerate case. */
+/** `malformed` wins over other classifications to prevent unsafe automatic repair. Otherwise `moved` wins over `deleted` when a single path's rows disagree on classification: `moved` means a relink candidate exists, which is the safer, more-actionable signal (relink instead of risk pruning a still-reachable link). In practice all rows for one path share a classification; this is a deterministic tie-break for the degenerate case. */
 
-!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]="e063d634-4306-5725-927a-5f2af1722458")}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]="1a4f19cf-56ba-571a-908c-97278a8284f7")}catch(e){}}();
 function preferClassification(current, next) {
+    if (current === "malformed" || next === "malformed")
+        return "malformed";
     return current === "moved" || next === "moved" ? "moved" : "deleted";
 }
 function ownerKey(input) {
@@ -91,4 +93,4 @@ export function summarizeMissingLinkedPathRows(rows) {
     return lines;
 }
 //# sourceMappingURL=missing-link-owners.js.map
-//# debugId=e063d634-4306-5725-927a-5f2af1722458
+//# debugId=1a4f19cf-56ba-571a-908c-97278a8284f7

package/dist/core/validate/stale-file-classification.d.ts

@@ -6,27 +6,29 @@
  *   scanned candidate set — the candidates are reported so an agent can relink
  *   the item to the new location instead of dropping the link, or
  * - `deleted`: no candidate with that basename exists anywhere in the scan,
- *   so the link points at content that is gone and pruning it is safe.
+ *   making it eligible for an explicitly requested prune, or
+ * - `malformed`: an ambiguous missing CSV or path:note literal which must be
+ *   reviewed before any relocation or removal is inferred.
  *
  * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the
  * already-collected candidate file list from the files check scan.
  */
 /** Classification labels for linked paths that no longer exist on disk. */
-export type StaleLinkedPathClassification = "moved" | "deleted";
+export type StaleLinkedPathClassification = "moved" | "deleted" | "malformed";
 /** Documents the classified stale linked path payload exchanged by command, SDK, and package integrations. */
 export interface ClassifiedStaleLinkedPath {
     /** Normalized workspace-relative stale linked path. */
     path: string;
     /** Value that configures or reports classification for this contract. */
     classification: StaleLinkedPathClassification;
-    /** Candidate new locations (same basename, different path), sorted and capped at `candidateLimit`. Empty for `deleted`. */
+    /** Candidate new locations (same basename, different path), sorted and capped at `candidateLimit`. Empty for `deleted` and `malformed`. */
     candidates: string[];
     /** True when more candidates existed than `candidateLimit` allowed. */
     candidates_truncated: boolean;
 }
 /** Fallback stale path candidate limit used when callers do not provide an override. */
 export declare const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;
-/** Classify each stale (missing) linked path as `moved` or `deleted` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
+/** Classify each stale (missing) linked path as `moved`, `deleted`, or `malformed` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
 export declare function classifyStaleLinkedPaths(stalePaths: readonly string[], candidateFiles: readonly string[], candidateLimit?: number): ClassifiedStaleLinkedPath[];
 /** Render compact `<path>:moved:<top-candidate>` / `<path>:deleted` rows for the files check details (token-efficient counterpart to the full classification objects). */
 export declare function summarizeStaleLinkedPathClassifications(classified: readonly ClassifiedStaleLinkedPath[]): string[];

package/dist/core/validate/stale-file-classification.js

@@ -6,20 +6,23 @@
  *   scanned candidate set — the candidates are reported so an agent can relink
  *   the item to the new location instead of dropping the link, or
  * - `deleted`: no candidate with that basename exists anywhere in the scan,
- *   so the link points at content that is gone and pruning it is safe.
+ *   making it eligible for an explicitly requested prune, or
+ * - `malformed`: an ambiguous missing CSV or path:note literal which must be
+ *   reviewed before any relocation or removal is inferred.
  *
  * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the
  * already-collected candidate file list from the files check scan.
  */
 /** Fallback stale path candidate limit used when callers do not provide an override. */
 
-!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]="5a5b0bd8-d99b-52fb-82ae-52ba48c54c30")}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]="eb4fe9bd-31b5-5ed3-b401-3e3776ec12e9")}catch(e){}}();
 export const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;
+/** Extract a basename from either portable separator convention. */
 function basenameOf(relativePath) {
     const lastSlash = Math.max(relativePath.lastIndexOf("/"), relativePath.lastIndexOf("\\"));
     return lastSlash === -1 ? relativePath : relativePath.slice(lastSlash + 1);
 }
-/** Classify each stale (missing) linked path as `moved` or `deleted` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
+/** Classify each stale (missing) linked path as `moved`, `deleted`, or `malformed` by matching its basename against the candidate file list. Output preserves the input order of `stalePaths` (callers pass an already-sorted unique list). A candidate equal to the stale path itself never matches (the path is known missing; an identical candidate would be self-referential noise). */
 export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLimit = DEFAULT_STALE_PATH_CANDIDATE_LIMIT) {
     const limit = Number.isFinite(candidateLimit) && candidateLimit >= 1
         ? Math.floor(candidateLimit)
@@ -39,6 +42,18 @@ export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLi
         }
     }
     return stalePaths.map((stalePath) => {
+        // Historical CSV and path:note input must not become a confident basename
+        // relocation. Existing files are checked before classification; this only
+        // rejects ambiguous missing references, never an existing literal filename.
+        if (stalePath.includes(",") ||
+            stalePath.replace(/^[a-z]:[\\/]/i, "").includes(":")) {
+            return {
+                path: stalePath,
+                classification: "malformed",
+                candidates: [],
+                candidates_truncated: false,
+            };
+        }
         const matches = (candidatesByBasename.get(basenameOf(stalePath)) ?? [])
             .filter((candidate) => candidate !== stalePath)
             .sort((left, right) => left.localeCompare(right));
@@ -62,7 +77,7 @@ export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLi
 export function summarizeStaleLinkedPathClassifications(classified) {
     return classified.map((entry) => entry.classification === "moved"
         ? `${entry.path}:moved:${entry.candidates[0]}`
-        : `${entry.path}:deleted`);
+        : `${entry.path}:${entry.classification}`);
 }
 //# sourceMappingURL=stale-file-classification.js.map
-//# debugId=5a5b0bd8-d99b-52fb-82ae-52ba48c54c30
+//# debugId=eb4fe9bd-31b5-5ed3-b401-3e3776ec12e9

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="71cfdc6b-c990-51b6-a9ae-ed9bf98136f7")}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]="1950da06-8c27-5506-bc64-4bf51c1a3f1c")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -410,11 +410,13 @@ async function emitMcpChangeNotifications(action) {
     }
     pruneClosedMcpSubscriptionRegistries();
 }
+/** Resolve one tool's workspace and scope SDK attribution to that request without changing process environment. */
 async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegotiated = false) {
+    const clientSignals = clientInfo ? { client_info: clientInfo } : {};
     return runWithHarnessDetectionSignals({
         env: process.env,
         argv: process.argv,
-        ...(clientInfo ? { client_info: clientInfo } : {}),
+        ...clientSignals,
     }, async () => {
         const params = asRecordClone(paramsInput);
         const name = readRequiredString(params, "name");
@@ -454,7 +456,12 @@ async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegot
         const workspaceIdentity = (await pathExists(getSettingsPath(pmRoot)))
             ? (await readSettings(pmRoot)).agent_identity
             : undefined;
-        return runWithWorkspaceHarnessSignalDescriptors(workspaceIdentity?.harness_signals ?? [], async () => {
+        return runWithHarnessDetectionSignals({
+            env: { ...process.env, PM_PATH: pmRoot },
+            argv: process.argv,
+            cwd,
+            ...clientSignals,
+        }, () => runWithWorkspaceHarnessSignalDescriptors(workspaceIdentity?.harness_signals ?? [], async () => {
             // pm-qxwu: non-breaking detection of typo'd / unexpected top-level keys.
             // additionalProperties stays true so passthrough still works; we only warn.
             // pm-upi0 extends the same mechanism into the nested options object.
@@ -472,7 +479,7 @@ async function handleToolCall(paramsInput, clientInfo, progressiveDiscoveryNegot
             const result = await handler(args);
             void emitMcpChangeNotifications(action);
             return resultContent(result, warnings, args.tokenAccounting === true, progressiveDiscoveryNegotiated);
-        }, { probesEnabled: workspaceIdentity?.probes_enabled });
+        }, { probesEnabled: workspaceIdentity?.probes_enabled }));
     });
 }
 /** Open one modern subscription through a concrete transport-owned sink. */
@@ -1225,4 +1232,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=71cfdc6b-c990-51b6-a9ae-ed9bf98136f7
+//# debugId=1950da06-8c27-5506-bc64-4bf51c1a3f1c

package/dist/sdk/actionability.d.ts

@@ -7,4 +7,4 @@
  * blocker or ready-work classifications without storage or rendering side
  * effects.
  */
-export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, resolveItemExecutionRole, selectActionableEntries, type ActionabilitySelectionOptions, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";

package/dist/sdk/actionability.js

@@ -8,7 +8,7 @@
  * effects.
  */
 
-!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]="cc271a73-9767-54bb-a142-d4d4569e3c6a")}catch(e){}}();
-export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, } from "../core/item/actionability.js";
+!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]="7d393eb0-d24d-55d2-8e4e-e94805d91784")}catch(e){}}();
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, resolveItemExecutionRole, selectActionableEntries, } from "../core/item/actionability.js";
 //# sourceMappingURL=actionability.js.map
-//# debugId=cc271a73-9767-54bb-a142-d4d4569e3c6a
+//# debugId=7d393eb0-d24d-55d2-8e4e-e94805d91784

package/dist/sdk/cli-contracts/command-aliases.js

@@ -10,8 +10,17 @@
  * are intentionally absent from default help and completion discovery.
  */
 
-!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]="3c9694bd-3635-5298-abeb-6899c94317ab")}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]="a7934e70-b1ea-5eac-b500-e4b18a6385a6")}catch(e){}}();
 export const PM_COMMAND_ALIAS_CONTRACTS = [
+    {
+        alias: "tests",
+        canonical: "test",
+        canonical_argv: ["test"],
+        lifecycle: "permanent",
+        hidden: false,
+        registration: "bootstrap",
+        owner: "pm-u4t9gp",
+    },
     ...[
         ["fetch", "get"],
         ["read", "get"],
@@ -96,4 +105,4 @@ export function renderPmCommandAliasMigrationHint(contract) {
     return `Deprecated command \`${contract.alias}\`; use \`pm ${contract.canonical_argv.join(" ")}\`.`;
 }
 //# sourceMappingURL=command-aliases.js.map
-//# debugId=3c9694bd-3635-5298-abeb-6899c94317ab
+//# debugId=a7934e70-b1ea-5eac-b500-e4b18a6385a6

package/dist/sdk/cli-contracts/completeness.js

@@ -7,7 +7,7 @@
  * a hand-picked test list.
  */
 
-!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]="f4e5eed5-94c2-536a-8685-e20b735de480")}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]="199e3ef5-93a0-5d93-8f77-d9d12bbc69d4")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -100,6 +100,7 @@ const ACTION_POSITIONAL_PARAMETERS = {
     },
 };
 const ACTION_FLAG_PARAMETER_OVERRIDES = {
+    append: { "--text": "body" },
     assurance: {
         "--tree": "treeId",
         "--owner": "owner",
@@ -139,7 +140,7 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     docs: { "--note": "addNote" },
     comments: { "--full-history": "full" },
     notes: { "--file": "text", "--full-history": "full" },
-    learnings: { "--full-history": "full" },
+    learnings: { "--file": "text", "--full-history": "full" },
     gc: { "--scope": "gcScope" },
     contracts: { "--action": "contractAction" },
     schema: {
@@ -390,4 +391,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=f4e5eed5-94c2-536a-8685-e20b735de480
+//# debugId=199e3ef5-93a0-5d93-8f77-d9d12bbc69d4

package/dist/sdk/cli-contracts/flag-contracts.d.ts

@@ -21,6 +21,8 @@ export interface CliFlagContract {
     value_type?: "string" | "number" | "boolean";
     /** Marks a presentation-only flag that may change paging or rendering without invalidating continuation. Omission means the flag is query-semantic. */
     cursor_semantics?: "presentation";
+    /** Host reservation boundary: inherited flags are forbidden on extensions; root-only flags may have command-local meanings. */
+    reservation_scope?: "inherited" | "root_only";
 }
 /** Maps an MCP tool option `param` to the CLI `flag` it forwards to, plus the value semantics (`allowEmpty`, `repeatable`, `booleanish`) the bridge needs to translate a structured tool call into argv. */
 export interface ToolOptionFlagContract {

package/dist/sdk/cli-contracts/flag-contracts.js

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="789faf62-dfbf-56ff-9412-55adc5c12d3d")}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]="573d318a-5ebe-5547-8be7-16026a077c84")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
@@ -67,13 +67,16 @@ export function compactFlagAliasContracts(flagContracts) {
 /** Public contract for subcommand global flag contracts, shared by SDK and presentation-layer consumers. */
 export const SUBCOMMAND_GLOBAL_FLAG_CONTRACTS = RESERVED_EXTENSION_HOST_FLAGS.map((definition) => ({
     flag: definition.flag,
+    reservation_scope: "inherited",
     ...(definition.aliases ? { aliases: [...definition.aliases] } : {}),
     ...(definition.value_name ? { value_name: definition.value_name } : {}),
 }));
 /** Public contract for global flag contracts, shared by SDK and presentation-layer consumers. */
 export const GLOBAL_FLAG_CONTRACTS = [
     ...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS,
-    { flag: "--version" },
+    { flag: "--version", value_type: "boolean", reservation_scope: "root_only" },
+    { flag: "--all", value_type: "boolean", reservation_scope: "root_only", description: "Expand root help to every command." },
+    { flag: "--explain", value_type: "boolean", reservation_scope: "root_only", description: "Expand root help with command guidance." },
 ];
 /** Governance-missing (GH-236) + content-field presence/absence (GH-242) selection-filter flags shared verbatim by the `list` and `search` flag tables. Module-private on purpose — spread into both tables at the same position so the published contract order is unchanged. */
 const GOVERNANCE_AND_CONTENT_FILTER_FLAG_CONTRACTS = [
@@ -259,6 +262,10 @@ export const NOTES_FLAG_CONTRACTS = [
 export const LEARNINGS_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
     { flag: "--add", aliases: ["--learning", "--text"] },
+    { flag: "--stdin" },
+    { flag: "--file" },
+    { flag: "--edit" },
+    { flag: "--delete" },
     { flag: "--limit" },
     { flag: "--full-history" },
     { flag: "--if-absent", value_type: "boolean" },
@@ -327,6 +334,9 @@ export const HISTORY_FLAG_CONTRACTS = [
 /** Public contract for merge flag contracts, shared by SDK and presentation-layer consumers. */
 export const MERGE_FLAG_CONTRACTS = [
     { flag: "--dry-run" },
+    { flag: "--message" },
+    { flag: "--force" },
+    { flag: "--include-reconciled" },
     { flag: "--output" },
     { flag: "--item-path" },
     { flag: "--prefer" },
@@ -348,6 +358,7 @@ export const HISTORY_REPAIR_FLAG_CONTRACTS = [
     { flag: "--all" },
     { flag: "--dry-run" },
     { flag: "--normalize-provenance" },
+    { flag: "--salvage-tail", value_type: "boolean" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -545,6 +556,7 @@ export const INIT_FLAG_CONTRACTS = [
 ];
 /** Public contract for config flag contracts, shared by SDK and presentation-layer consumers. */
 export const CONFIG_FLAG_CONTRACTS = [
+    { flag: "--value", value_name: "value" },
     { flag: "--criterion" },
     { flag: "--clear-criteria" },
     { flag: "--format" },
@@ -781,6 +793,7 @@ export const CLOSE_MANY_FLAG_CONTRACTS = [
 export const APPEND_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
     { flag: "--body", short: "-b" },
+    { flag: "--text" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -802,6 +815,8 @@ export const CLAIM_FLAG_CONTRACTS = [
     { flag: "--release" },
     { flag: "--max-attempts" },
     { flag: "--include-decisions" },
+    { flag: "--include-gates" },
+    { flag: "--include-containers" },
     { flag: "--token-budget", aliases: ["--token_budget"] },
     { flag: "--explain-ranking", aliases: ["--explain_ranking"] },
 ];
@@ -880,6 +895,7 @@ export const REMIND_FLAG_CONTRACTS = [
 ];
 /** Public contract for test flag contracts, shared by SDK and presentation-layer consumers. */
 export const TEST_FLAG_CONTRACTS = [
+    { flag: "--list" },
     { flag: "--id", value_name: "item-id" },
     { flag: "--add" },
     { flag: "--add-json" },
@@ -969,6 +985,7 @@ export const STATS_FLAG_CONTRACTS = [
 ];
 /** Public contract for duplicate-cluster discovery flags. */
 export const DUPLICATES_FLAG_CONTRACTS = [
+    { flag: "--exhaustive", value_type: "boolean" },
     { flag: "--status", repeatable: true, list: true },
     { flag: "--since" },
     { flag: "--threshold" },
@@ -1282,6 +1299,12 @@ export const UPDATE_FLAG_CONTRACTS = [
 ];
 /** Public contract for update many flag contracts, shared by SDK and presentation-layer consumers. */
 export const UPDATE_MANY_FLAG_CONTRACTS = [
+    { flag: "--status", short: "-s" },
+    { flag: "--assignee" },
+    { flag: "--parent" },
+    { flag: "--blocked-by", aliases: ["--blocked_by"] },
+    { flag: "--blocked-reason", aliases: ["--blocked_reason"] },
+    { flag: "--unblock-note", aliases: ["--unblock_note"] },
     { flag: "--filter-status", list: true },
     { flag: "--filter-type", list: true },
     { flag: "--filter-tag", list: true },
@@ -1559,6 +1582,9 @@ export const WORKSPACE_FLAG_CONTRACTS = [
 export const WORKSPACE_POSITION_FLAG_CONTRACTS = [];
 /** Public contract for next flag contracts, shared by SDK and presentation-layer consumers. */
 export const NEXT_FLAG_CONTRACTS = [
+    { flag: "--include-decisions" },
+    { flag: "--include-gates" },
+    { flag: "--include-containers" },
     { flag: "--for", value_name: "intent" },
     { flag: "--type" },
     { flag: "--tag" },
@@ -1694,7 +1720,6 @@ const FIXED_STATUS_LIST_COMMAND_ALIASES = [
     "list-canceled",
 ];
 const FIXED_STATUS_LIST_FLAG_CONTRACTS = LIST_FILTER_FLAG_CONTRACTS.filter((contract) => contract.flag !== "--status" && contract.flag !== "--all");
-const ALL_STATUS_LIST_FLAG_CONTRACTS = LIST_FILTER_FLAG_CONTRACTS.filter((contract) => contract.flag !== "--status");
 function indexCliFlagContracts(contracts) {
     const index = new Map();
     for (const contract of contracts) {
@@ -1741,7 +1766,7 @@ export const PM_POSITIONAL_ACTION_FLAG_CONTRACTS = resolvePmPositionalActionFlag
 // member such as `constructor` or `toString`.
 const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["list", LIST_FILTER_FLAG_CONTRACTS],
-    ["list-all", ALL_STATUS_LIST_FLAG_CONTRACTS],
+    ["list-all", LIST_FILTER_FLAG_CONTRACTS],
     ...FIXED_STATUS_LIST_COMMAND_ALIASES.map((command) => [
         command,
         FIXED_STATUS_LIST_FLAG_CONTRACTS,
@@ -1759,6 +1784,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["install", INSTALL_FLAG_CONTRACTS],
     ["upgrade", UPGRADE_FLAG_CONTRACTS],
     ["create", CREATE_FLAG_CONTRACTS],
+    ["item", []],
     ["item mutate", ITEM_MUTATE_FLAG_CONTRACTS],
     ["item complete", ITEM_COMPLETE_FLAG_CONTRACTS],
     ["item reopen", ITEM_REOPEN_FLAG_CONTRACTS],
@@ -1919,4 +1945,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=789faf62-dfbf-56ff-9412-55adc5c12d3d
+//# debugId=573d318a-5ebe-5547-8be7-16026a077c84