@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/sdk/agent/tracker-preflight-contracts.js

@@ -0,0 +1,127 @@
+/**
+ * @module sdk/agent/tracker-preflight-contracts
+ *
+ * Declares and scores executable recovery for tracker filesystem preflight failures.
+ */
+
+!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]="941a11a9-f756-56b3-9dc1-8afd78bc9328")}catch(e){}}();
+const TRACKER_PREFLIGHT_RECOVERY_CONTRACTS = [
+    {
+        probe_id: "tracker-root-missing",
+        failure_kind: "missing_root",
+        expected_error_code: "tracker_root_missing",
+        expected_exit_code: 3,
+        recovery_kind: "initialize",
+    },
+    {
+        probe_id: "tracker-root-settings-missing",
+        failure_kind: "settings_missing",
+        expected_error_code: "tracker_not_initialized",
+        expected_exit_code: 3,
+        recovery_kind: "initialize",
+    },
+    {
+        probe_id: "tracker-root-not-directory",
+        failure_kind: "not_directory",
+        expected_error_code: "tracker_root_not_directory",
+        expected_exit_code: 2,
+        recovery_kind: "select_directory",
+    },
+    {
+        probe_id: "tracker-root-unreadable",
+        failure_kind: "unreadable_root",
+        expected_error_code: "tracker_root_unreadable",
+        expected_exit_code: 1,
+        recovery_kind: "repair_permissions",
+    },
+];
+/** Return defensive copies of every core tracker preflight recovery contract. */
+export function listTrackerPreflightRecoveryContracts() {
+    return TRACKER_PREFLIGHT_RECOVERY_CONTRACTS.map((contract) => ({
+        ...contract,
+    }));
+}
+function findTrackerPreflightObservationFindings(contract, observation) {
+    const findings = [];
+    if (observation.error_code !== contract.expected_error_code) {
+        findings.push({
+            code: "error_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected ${contract.expected_error_code}, received ${observation.error_code}.`,
+        });
+    }
+    if (observation.exit_code !== contract.expected_exit_code) {
+        findings.push({
+            code: "exit_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected exit ${contract.expected_exit_code}, received ${observation.exit_code}.`,
+        });
+    }
+    if (observation.recovery_kind !== contract.recovery_kind) {
+        findings.push({
+            code: "recovery_kind_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected ${contract.recovery_kind}, received ${observation.recovery_kind}.`,
+        });
+    }
+    const initIndex = observation.suggested_retry_args.indexOf("init");
+    const validInitCommand = initIndex === 0 ||
+        (initIndex === 2 &&
+            observation.suggested_retry_args[0] === "--pm-path" &&
+            observation.suggested_retry_args[1]?.length > 0);
+    if (contract.recovery_kind === "initialize" && !validInitCommand) {
+        findings.push({
+            code: "missing_init_recovery",
+            probe_id: contract.probe_id,
+            detail: "Missing and uninitialized roots must emit a tokenized init retry.",
+        });
+    }
+    if (observation.unsafe_init_recommended ||
+        (contract.recovery_kind !== "initialize" &&
+            observation.suggested_retry_args.includes("init"))) {
+        findings.push({
+            code: "unsafe_init_recovery",
+            probe_id: contract.probe_id,
+            detail: "A tracker root that cannot be initialized safely must not recommend initialization.",
+        });
+    }
+    if (!observation.retry_succeeded) {
+        findings.push({
+            code: "retry_failed",
+            probe_id: contract.probe_id,
+            detail: "The emitted retry or safe alternate-root recovery did not execute successfully.",
+        });
+    }
+    return findings;
+}
+/** Score runtime observations against the complete tracker preflight recovery corpus. */
+export function scoreTrackerPreflightRecoveryClosure(observations) {
+    const observationsByProbe = new Map(observations.map((observation) => [observation.probe_id, observation]));
+    const findings = [];
+    let closedProbeCount = 0;
+    for (const contract of TRACKER_PREFLIGHT_RECOVERY_CONTRACTS) {
+        const observation = observationsByProbe.get(contract.probe_id);
+        if (observation === undefined) {
+            findings.push({
+                code: "missing_probe",
+                probe_id: contract.probe_id,
+                detail: "No runtime observation was supplied for this contract.",
+            });
+            continue;
+        }
+        const observationFindings = findTrackerPreflightObservationFindings(contract, observation);
+        findings.push(...observationFindings);
+        if (observationFindings.length === 0)
+            closedProbeCount += 1;
+    }
+    findings.sort((left, right) => left.probe_id.localeCompare(right.probe_id) ||
+        left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        probe_count: TRACKER_PREFLIGHT_RECOVERY_CONTRACTS.length,
+        closed_probe_count: closedProbeCount,
+        findings,
+    };
+}
+//# sourceMappingURL=tracker-preflight-contracts.js.map
+//# debugId=941a11a9-f756-56b3-9dc1-8afd78bc9328

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!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]="dd74bc56-9971-59b9-8d2b-a6cc78b0a650")}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]="5e77c121-35a2-57d1-9a3e-f33447535c03")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -87,6 +87,7 @@ const COMMANDS_BY_FAMILY = Object.freeze({
         "close-task",
         "delete",
         "pause-task",
+        "item-reopen",
         "release",
         "start-task",
         "update",
@@ -107,13 +108,7 @@ const COMMANDS_BY_FAMILY = Object.freeze({
         "notes",
     ]),
     graph: new Set(["deps", "graph", "plan"]),
-    quality: new Set([
-        "assurance",
-        "contracts",
-        "test",
-        "test-all",
-        "validate",
-    ]),
+    quality: new Set(["assurance", "contracts", "test", "test-all", "validate"]),
     automation: new Set(["event", "meet", "remind"]),
 });
 const EXTENSION_COMMANDS = new Set([
@@ -140,7 +135,7 @@ export function resolvePmCommandCapabilityFamily(command) {
  * by normal help or completion projections.
  */
 export const PM_COMMAND_CAPABILITY_CONTRACTS = Object.freeze([
-    ...PM_CORE_COMMAND_NAMES.map((command) => ({
+    ...PM_CORE_COMMAND_NAMES.flatMap((command) => command === "item" ? ["item-reopen"] : [command]).map((command) => ({
         command,
         tier: CORE_COMMANDS.has(command)
             ? "core"
@@ -181,7 +176,7 @@ const TIER_ORDER = {
 const COMMAND_TIER_BY_NAME = new Map(PM_COMMAND_VISIBILITY_CONTRACTS.map(({ command, tier }) => [command, tier]));
 /** Resolve one command's declared tier; extension commands default to standard. */
 export function resolvePmCommandVisibilityTier(command, extensionTier = "standard") {
-    return COMMAND_TIER_BY_NAME.get(command.trim().toLowerCase()) ?? extensionTier;
+    return (COMMAND_TIER_BY_NAME.get(command.trim().toLowerCase()) ?? extensionTier);
 }
 /** Return commands visible at a requested tier, preserving contract order. */
 export function listPmCommandsForTier(tier) {
@@ -327,4 +322,4 @@ export function renderPmCommandVisibilityMarkdown() {
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=dd74bc56-9971-59b9-8d2b-a6cc78b0a650
+//# debugId=5e77c121-35a2-57d1-9a3e-f33447535c03

package/dist/sdk/annotations.js

@@ -4,9 +4,10 @@
  * Implements the pm annotation command 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]="0af9967c-ca72-563a-9518-2e68da0c0fe0")}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]="eac75dc5-80b4-50d2-b615-4f96edca7346")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { readFile } from "node:fs/promises";
-import { isFileAbsentError, pathExists } from "../core/fs/fs-utils.js";
+import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { createStdinTokenResolver, parseCsvKv } from "../core/item/parse.js";
@@ -16,7 +17,7 @@ import { parseLimit } from "../core/shared/numeric-parsers.js";
 import { nowIso } from "../core/shared/time.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 /** Map transport-level `full` onto the SDK annotation history option. */
 export function normalizeAnnotationTransportOptions(options) {
@@ -215,9 +216,7 @@ function assertAnnotationMessageHasTextSource(config, options) {
 export async function runAnnotationCommand(id, options, global, config) {
     assertAnnotationMessageHasTextSource(config, options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const limit = parseLimit(options.limit);
@@ -399,4 +398,4 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=0af9967c-ca72-563a-9518-2e68da0c0fe0
+//# debugId=eac75dc5-80b4-50d2-b615-4f96edca7346

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]="8b227cb2-a30d-5384-b9c2-558603181c67")}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]="f4e5eed5-94c2-536a-8685-e20b735de480")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -63,6 +63,8 @@ const CLI_CONFIG_SHORTHAND_FLAGS = new Set([
 ]);
 const SDK_TRANSPORT_PARAMETERS = new Set([
     "action",
+    "fullChangedFields",
+    "idOnly",
     "path",
     "pmExecutable",
     "timeoutMs",
@@ -87,6 +89,7 @@ const ACTION_POSITIONAL_PARAMETERS = {
     event: { title: "<title>" },
     files: { lookupPath: "lookup <path...>" },
     meet: { title: "<title>" },
+    "item-reopen": { id: "<id>", reason: "<reason>" },
     merge: { subcommand: "<subcommand>" },
     remind: { title: "<title>" },
     workspace: {
@@ -188,6 +191,9 @@ function actionCommand(action) {
     if (action.startsWith("package-")) {
         return `package ${action.slice("package-".length)}`;
     }
+    if (action.startsWith("item-")) {
+        return `item ${action.slice("item-".length)}`;
+    }
     return action;
 }
 function parameterForFlag(action, flag) {
@@ -384,4 +390,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=8b227cb2-a30d-5384-b9c2-558603181c67
+//# debugId=f4e5eed5-94c2-536a-8685-e20b735de480

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

@@ -30,17 +30,19 @@ export declare const GRAPH_SUBCOMMAND_VALUES: readonly ["ancestors", "descendant
 export type GraphSubcommand = (typeof GRAPH_SUBCOMMAND_VALUES)[number];
 /** Nested lifecycle verbs flattened by SDK and MCP package actions. */
 export declare const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS: readonly ["init", "install", "uninstall", "explore", "manage", "describe", "reload", "doctor", "catalog", "adopt", "adopt-all", "activate", "deactivate"];
+/** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */
+export declare const PM_ITEM_ACTION_SUBCOMMANDS: readonly ["reopen"];
 /** CLI-only presentation commands intentionally omitted from programmatic actions. */
 export declare const PM_CLI_ONLY_TOOL_ACTION_WAIVERS: {
     readonly help: "Commander help rendering has no SDK operation result.";
-    readonly item: "The item namespace only groups lifecycle subcommands already exposed as actions.";
     readonly packages: "The plural package alias only renders package-oriented help.";
 };
 type PmCoreCommandName = (typeof PM_CORE_COMMAND_NAMES)[number];
 type PmCliOnlyToolAction = keyof typeof PM_CLI_ONLY_TOOL_ACTION_WAIVERS;
 type PmExtensionPackageAction = `${"extension" | "package"}-${(typeof PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS)[number]}`;
+type PmItemAction = `item-${(typeof PM_ITEM_ACTION_SUBCOMMANDS)[number]}`;
 /** Restricts pm tool action values accepted by command, SDK, and storage contracts. */
-export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction> | PmExtensionPackageAction;
+export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction | "item"> | PmExtensionPackageAction | PmItemAction;
 /**
  * Public pm tool actions derived from the CLI vocabulary. Nested extension and
  * package verbs are flattened for transports that expose one action string.

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

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Enum Contracts.
  */
 
-!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]="d05ce92b-bee8-5cce-afc2-8c7901306a30")}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]="8b8b6b8e-5061-5da4-a369-eca379c0090b")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_SERVICE_NAMES, KNOWN_EXTENSION_TRUST_MODES, } from "../../core/extensions/extension-types.js";
 import { PM_COMMAND_ALIAS_CONTRACTS } from "./command-aliases.js";
 /** Public contract for pm extension capability contracts, shared by SDK and presentation-layer consumers. */
@@ -140,10 +140,11 @@ export const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS = [
     "activate",
     "deactivate",
 ];
+/** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */
+export const PM_ITEM_ACTION_SUBCOMMANDS = ["reopen"];
 /** CLI-only presentation commands intentionally omitted from programmatic actions. */
 export const PM_CLI_ONLY_TOOL_ACTION_WAIVERS = {
     help: "Commander help rendering has no SDK operation result.",
-    item: "The item namespace only groups lifecycle subcommands already exposed as actions.",
     packages: "The plural package alias only renders package-oriented help.",
 };
 /**
@@ -159,6 +160,9 @@ export const PM_TOOL_ACTIONS = Object.freeze(PM_CORE_COMMAND_NAMES.flatMap((comm
             command,
         ];
     }
+    if (command === "item") {
+        return PM_ITEM_ACTION_SUBCOMMANDS.map((subcommand) => `item-${subcommand}`);
+    }
     return [command];
 }));
 /** Deprecated compatibility actions accepted by the SDK but omitted from canonical MCP discovery. */
@@ -172,9 +176,15 @@ export function analyzePmToolActionParity(cliCommands = PM_CORE_COMMAND_NAMES, t
     const toolActionSet = new Set(toolActions);
     const cliCommandSet = new Set(cliCommands);
     return {
-        missing_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) && waivers[command] === undefined),
-        waived_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) && waivers[command] !== undefined),
-        stale_waivers: Object.keys(waivers).filter((command) => !cliCommandSet.has(command) || toolActionSet.has(command)),
+        missing_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) &&
+            !toolActions.some((action) => action.startsWith(`${command}-`)) &&
+            waivers[command] === undefined),
+        waived_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) &&
+            !toolActions.some((action) => action.startsWith(`${command}-`)) &&
+            waivers[command] !== undefined),
+        stale_waivers: Object.keys(waivers).filter((command) => !cliCommandSet.has(command) ||
+            toolActionSet.has(command) ||
+            toolActions.some((action) => action.startsWith(`${command}-`))),
     };
 }
 /** Implements check whether pm tool action for the public runtime surface of this module. */
@@ -198,4 +208,4 @@ export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
 //# sourceMappingURL=enum-contracts.js.map
-//# debugId=d05ce92b-bee8-5cce-afc2-8c7901306a30
+//# debugId=8b8b6b8e-5061-5da4-a369-eca379c0090b

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

@@ -177,6 +177,8 @@ export declare const CREATE_FLAG_CONTRACTS: CliFlagContract[];
 export declare const ITEM_MUTATE_FLAG_CONTRACTS: CliFlagContract[];
 /** Atomic item-completion flags shared by contracts, help, and completions. */
 export declare const ITEM_COMPLETE_FLAG_CONTRACTS: CliFlagContract[];
+/** Recurrence transition flags shared by CLI, SDK, MCP, help, and completion. */
+export declare const ITEM_REOPEN_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for copy flag contracts, shared by SDK and presentation-layer consumers. */
 export declare const COPY_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for focus flag contracts, shared by SDK and presentation-layer consumers. */

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]="505e9b6b-a62a-5981-8862-619624246170")}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]="e302f519-aa51-503b-bd1a-f3155338f133")}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";
@@ -1188,6 +1188,14 @@ export const ITEM_COMPLETE_FLAG_CONTRACTS = [
     { flag: "--force" },
     { flag: "--author", value_name: "value" },
 ];
+/** Recurrence transition flags shared by CLI, SDK, MCP, help, and completion. */
+export const ITEM_REOPEN_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
+    { flag: "--status", value_name: "open|in_progress" },
+    { flag: "--message", value_name: "value" },
+    { flag: "--force" },
+    { flag: "--author", value_name: "value" },
+];
 /** Public contract for copy flag contracts, shared by SDK and presentation-layer consumers. */
 export const COPY_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
@@ -1740,6 +1748,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["create", CREATE_FLAG_CONTRACTS],
     ["item mutate", ITEM_MUTATE_FLAG_CONTRACTS],
     ["item complete", ITEM_COMPLETE_FLAG_CONTRACTS],
+    ["item reopen", ITEM_REOPEN_FLAG_CONTRACTS],
     ["copy", COPY_FLAG_CONTRACTS],
     ["focus", FOCUS_FLAG_CONTRACTS],
     ["aggregate", AGGREGATE_FLAG_CONTRACTS],
@@ -1892,4 +1901,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=505e9b6b-a62a-5981-8862-619624246170
+//# debugId=e302f519-aa51-503b-bd1a-f3155338f133

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

@@ -16,6 +16,15 @@ export interface PmFlagLexiconEntry {
     /** Parsed value shape. */
     value_kind: PmFlagValueKind;
 }
+/** Persistable compatibility inventory for one canonical command flag. */
+export interface PmFlagSpellingInventoryEntry {
+    /** Canonical command path. */
+    command: string;
+    /** Canonical long spelling generated for new callers. */
+    canonical_flag: string;
+    /** Every executable long spelling, including compatibility aliases. */
+    accepted_spellings: readonly string[];
+}
 /** Ratcheted canonical flag budget for one command. */
 export interface PmCommandFlagBudget {
     /** Canonical command path. */
@@ -28,7 +37,7 @@ export interface PmCommandFlagBudget {
 /** One fail-closed lexicon or budget violation. */
 export interface PmFlagLexiconFinding {
     /** Stable finding code. */
-    code: "alias_collision" | "budget_exceeded" | "duplicate_canonical_flag" | "inconsistent_concept_kind" | "missing_budget" | "stale_budget";
+    code: "alias_collision" | "budget_exceeded" | "duplicate_canonical_flag" | "inconsistent_concept_kind" | "missing_budget" | "removed_canonical_spelling" | "removed_compatibility_spelling" | "semantic_spelling_collision" | "stale_budget";
     /** Canonical command path. */
     command: string;
     /** Human-readable finding detail. */
@@ -42,14 +51,22 @@ export interface PmFlagLexiconReport {
     entry_count: number;
     /** Number of command budgets checked. */
     budget_count: number;
+    /** Number of stable semantic concepts represented. */
+    concept_count: number;
+    /** Number of historical spelling rows checked. */
+    baseline_entry_count: number;
     /** Stable ordered findings. */
     findings: readonly PmFlagLexiconFinding[];
 }
+/** Resolve one executable command flag to its stable cross-command semantic concept. */
+export declare function resolvePmFlagSemanticConcept(command: string, flag: string): string;
 /** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
 export declare function listPmFlagLexicon(): readonly PmFlagLexiconEntry[];
+/** Return the complete canonical and compatibility spelling inventory. */
+export declare function listPmFlagSpellingInventory(): readonly PmFlagSpellingInventoryEntry[];
 /** Return persisted no-growth ratchets with current counts derived from the canonical vocabulary. */
 export declare function listPmCommandFlagBudgets(): readonly PmCommandFlagBudget[];
 /** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
-export declare function verifyPmFlagLexicon(entries?: readonly PmFlagLexiconEntry[], budgets?: readonly PmCommandFlagBudget[]): PmFlagLexiconReport;
+export declare function verifyPmFlagLexicon(entries?: readonly PmFlagLexiconEntry[], budgets?: readonly PmCommandFlagBudget[], baseline?: readonly PmFlagSpellingInventoryEntry[]): PmFlagLexiconReport;
 /** Render a compact, generated family and command budget reference. Persisted budget rows are initialized to an explicit fallback so stale rows remain renderable. */
 export declare function renderPmFlagLexiconMarkdown(): string;

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

@@ -5,12 +5,61 @@
  * per-command growth budgets.
  */
 
-!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]="19215662-5a8c-5b91-bc97-8dbdc1daff02")}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]="6ba3d756-dcd6-59b7-92fe-ec33d294d72b")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { PM_COMMAND_CAPABILITY_CONTRACTS, } from "../agent-capability-contracts.js";
 import { enrichCliFlagInvocationContracts } from "../flag-invocation-contracts.js";
 /** Memoized immutable canonical lexicon for this module instance. */
 let cachedPmFlagLexicon;
+const FULL_PROJECTION_CONCEPT_BY_COMMAND = Object.freeze({
+    list: "list-item-projection",
+    "list-all": "list-item-projection",
+    "list-draft": "list-item-projection",
+    "list-open": "list-item-projection",
+    "list-in-progress": "list-item-projection",
+    "list-blocked": "list-item-projection",
+    "list-closed": "list-item-projection",
+    "list-canceled": "list-item-projection",
+    get: "get-item-projection",
+    graph: "graph-detail-projection",
+    search: "search-result-projection",
+    history: "history-entry-projection",
+    events: "mutation-event-projection",
+    activity: "activity-entry-projection",
+    deps: "dependency-graph-projection",
+    health: "health-diagnostic-projection",
+    validate: "validation-diagnostic-projection",
+    contracts: "contract-catalog-projection",
+});
+/** Resolve one executable command flag to its stable cross-command semantic concept. */
+export function resolvePmFlagSemanticConcept(command, flag) {
+    if (flag === "--limit")
+        return "result-row-limit";
+    if (flag === "--node-limit")
+        return "graph-node-limit";
+    if (flag === "--edge-limit")
+        return "graph-edge-limit";
+    if (flag === "--output-limit")
+        return "rendered-output-row-limit";
+    if (flag === "--output-budget")
+        return "rendered-output-byte-budget";
+    if (flag === "--token-budget")
+        return "context-intent-token-budget";
+    if (flag === "--full") {
+        const concept = FULL_PROJECTION_CONCEPT_BY_COMMAND[command];
+        if (concept === undefined) {
+            throw new Error(`Command ${command} exposes --full without a registered projection concept.`);
+        }
+        return concept;
+    }
+    if (flag !== "--file")
+        return flag.slice(2);
+    if (["create", "update", "update-many"].includes(command))
+        return "linked-file-path";
+    if (["comments", "notes", "learnings"].includes(command))
+        return "entry-file-input";
+    return "plan-definition-file";
+}
 /** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
 export function listPmFlagLexicon() {
     if (cachedPmFlagLexicon !== undefined)
@@ -19,12 +68,14 @@ export function listPmFlagLexicon() {
     const provisionalEntries = commandContracts.flatMap(({ command, family }) => enrichCliFlagInvocationContracts(command, resolveSubcommandFlagContractsForCommand(command)).map((contract) => ({
         command,
         family,
-        concept: contract.flag.slice(2),
+        concept: resolvePmFlagSemanticConcept(command, contract.flag),
         flag: contract.flag,
         aliases: Object.freeze([...(contract.aliases ?? [])]),
         value_kind: (contract.repeatable
             ? "list"
-            : contract.value_type),
+            : contract.flag === "--limit"
+                ? "number"
+                : contract.value_type),
     })));
     const compatibilityAliasFlags = new Set(provisionalEntries.flatMap((entry) => entry.aliases.map((alias) => `${entry.command}:${alias}`)));
     const canonicalEntries = provisionalEntries.filter((entry) => !compatibilityAliasFlags.has(`${entry.command}:${entry.flag}`));
@@ -42,6 +93,14 @@ export function listPmFlagLexicon() {
     })));
     return cachedPmFlagLexicon;
 }
+/** Return the complete canonical and compatibility spelling inventory. */
+export function listPmFlagSpellingInventory() {
+    return Object.freeze(listPmFlagLexicon().map((entry) => Object.freeze({
+        command: entry.command,
+        canonical_flag: entry.flag,
+        accepted_spellings: Object.freeze([...new Set([entry.flag, ...entry.aliases])].sort()),
+    })));
+}
 const PM_COMMAND_FLAG_BUDGET_MAXIMUMS = Object.freeze({
     init: 30,
     config: 35,
@@ -171,11 +230,38 @@ function appendBudgetFindings(counts, budgets, findings) {
         });
     }
 }
+/** Append regressions against the persisted pre-change spelling inventory. */
+function appendSpellingCompatibilityFindings(entries, baseline, findings) {
+    const current = new Map(entries.map((entry) => [`${entry.command}:${entry.flag}`, entry]));
+    for (const historical of baseline) {
+        const key = `${historical.command}:${historical.canonical_flag}`;
+        const entry = current.get(key);
+        if (!entry) {
+            findings.push({
+                code: "removed_canonical_spelling",
+                command: historical.command,
+                detail: `${historical.canonical_flag} disappeared from the executable spelling inventory.`,
+            });
+            continue;
+        }
+        const accepted = new Set([entry.flag, ...entry.aliases]);
+        for (const spelling of historical.accepted_spellings) {
+            if (accepted.has(spelling))
+                continue;
+            findings.push({
+                code: "removed_compatibility_spelling",
+                command: historical.command,
+                detail: `${spelling} no longer resolves to ${historical.canonical_flag}.`,
+            });
+        }
+    }
+}
 /** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
-export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = listPmCommandFlagBudgets()) {
+export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = listPmCommandFlagBudgets(), baseline = []) {
     const findings = [];
     const canonicalOwners = new Map();
     const conceptKinds = new Map();
+    const conceptSpellings = new Map();
     const counts = new Map();
     for (const entry of entries) {
         const commandFlag = `${entry.command}:${entry.flag}`;
@@ -201,9 +287,21 @@ export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = lis
         else {
             conceptKinds.set(entry.concept, entry.value_kind);
         }
+        const priorSpelling = conceptSpellings.get(entry.concept);
+        if (priorSpelling !== undefined && priorSpelling !== entry.flag) {
+            findings.push({
+                code: "semantic_spelling_collision",
+                command: entry.command,
+                detail: `${entry.concept} is canonicalized by both ${priorSpelling} and ${entry.flag}.`,
+            });
+        }
+        else {
+            conceptSpellings.set(entry.concept, entry.flag);
+        }
     }
     appendAliasCollisionFindings(entries, canonicalOwners, findings);
     appendBudgetFindings(counts, budgets, findings);
+    appendSpellingCompatibilityFindings(entries, baseline, findings);
     findings.sort((left, right) => left.command.localeCompare(right.command) ||
         left.code.localeCompare(right.code) ||
         left.detail.localeCompare(right.detail));
@@ -211,6 +309,8 @@ export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = lis
         ok: findings.length === 0,
         entry_count: entries.length,
         budget_count: budgets.length,
+        concept_count: new Set(entries.map(({ concept }) => concept)).size,
+        baseline_entry_count: baseline.length,
         findings,
     };
 }
@@ -237,4 +337,4 @@ export function renderPmFlagLexiconMarkdown() {
     ].join("\n");
 }
 //# sourceMappingURL=flag-lexicon-contracts.js.map
-//# debugId=19215662-5a8c-5b91-bc97-8dbdc1daff02
+//# debugId=6ba3d756-dcd6-59b7-92fe-ec33d294d72b

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

@@ -10,7 +10,7 @@ import type { PmCommandAliasContract } from "./command-aliases.js";
 /** Canonical top-level domains an agent must retain to route pm operations. */
 export declare const PM_CLI_GRAMMAR_NOUNS: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
 /** Shared verbs whose meaning transfers across domain nouns. */
-export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "repair", "restore", "run", "show", "uninstall", "verify"];
+export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
 /** Why a current command is permitted while the grammar migration proceeds. */
 export type PmCommandDestinationDisposition = "target_noun" | "consolidation" | "package_owned" | "keep_as_is";
 /** Exact destination decision for one command emitted by runtime contracts. */
@@ -78,7 +78,7 @@ export declare const PM_COMMAND_POSITIONAL_CONTRACTS: readonly PmCommandPosition
 /** Immutable grammar policy used by contracts and the CI gate. */
 export declare const PM_CLI_GRAMMAR_CONTRACT: {
     readonly nouns: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
-    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "repair", "restore", "run", "show", "uninstall", "verify"];
+    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
     readonly scope_before_verb: true;
     readonly visible_top_level_ceiling: 69;
     readonly ceiling_raise_requires_pm_item: true;