@unbrained/pm-cli 2026.8.18 → 2026.8.19

package/dist/sdk/agent/refusal-closure.js

@@ -0,0 +1,92 @@
+/**
+ * @module sdk/agent/refusal-closure
+ *
+ * Scores whether a structured refusal contains enough executable context for
+ * an agent to recover without another discovery round trip.
+ */
+
+!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]="65cfaa41-6f53-5339-8b55-c1a4d3660c5d")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+/** Return every closure defect contributed by one unique observation. */
+function listObservationFindings(observation) {
+    return [
+        observation.exit_code !== EXIT_CODE.USAGE
+            ? {
+                code: "non_refusal_exit",
+                probe_id: observation.probe_id,
+                detail: `${observation.entrypoint} returned exit code ${observation.exit_code}; a structured usage refusal must return ${EXIT_CODE.USAGE}.`,
+            }
+            : undefined,
+        observation.allowed_values.length === 0
+            ? {
+                code: "missing_allowed_values",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted its complete accepted value domain.",
+            }
+            : undefined,
+        observation.allowed_values.includes(observation.rejected_value)
+            ? {
+                code: "accepted_rejected_value",
+                probe_id: observation.probe_id,
+                detail: `${observation.rejected_value} is both rejected and advertised as allowed.`,
+            }
+            : undefined,
+        observation.suggested_retry.trim().length === 0
+            ? {
+                code: "missing_suggested_retry",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted an executable suggested retry.",
+            }
+            : undefined,
+        !observation.retry_succeeded
+            ? {
+                code: "retry_failed",
+                probe_id: observation.probe_id,
+                detail: "The advertised suggested retry did not succeed.",
+            }
+            : undefined,
+    ];
+}
+/** Score structured closed-domain refusals and executable retries. */
+export function scorePmRefusalClosure(observations) {
+    const findings = [];
+    const seen = new Set();
+    let closedProbeCount = 0;
+    if (observations.length === 0) {
+        findings.push({
+            code: "empty_corpus",
+            probe_id: "corpus",
+            detail: "At least one real refusal observation is required.",
+        });
+    }
+    for (const observation of observations) {
+        if (seen.has(observation.probe_id)) {
+            findings.push({
+                code: "duplicate_probe",
+                probe_id: observation.probe_id,
+                detail: `${observation.probe_id} was supplied more than once.`,
+            });
+            continue;
+        }
+        seen.add(observation.probe_id);
+        const findingCount = findings.length;
+        for (const finding of listObservationFindings(observation)) {
+            if (finding !== undefined)
+                findings.push(finding);
+        }
+        if (findings.length === findingCount)
+            closedProbeCount += 1;
+    }
+    findings.sort((left, right) => left.probe_id !== right.probe_id
+        ? left.probe_id.localeCompare(right.probe_id)
+        : left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        probe_count: seen.size,
+        closed_probe_count: closedProbeCount,
+        closure_fraction: seen.size === 0 ? 0 : closedProbeCount / seen.size,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-closure.js.map
+//# debugId=65cfaa41-6f53-5339-8b55-c1a4d3660c5d

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -37,7 +37,7 @@ export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[numbe
 /** Behavioral promise attached to a recovery reference. */
 export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
 /** Literal envelope fields recognized as recovery-reference producers. */
-export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "candidate_command" | "example" | "next_step" | "retry_command")[];
+export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "example" | "candidate_command" | "next_step" | "retry_command")[];
 /** One source file supplied to the producer-census analyzer. */
 export interface PmRecoveryProducerSource {
     /** Repository-relative source path. */

package/dist/sdk/agent-capability-contracts.d.ts

@@ -1,5 +1,7 @@
 /** Visibility tiers shared by CLI help, completions, docs, extensions, and MCP. */
 export type PmCommandVisibilityTier = "core" | "standard" | "full" | "internal";
+/** Stable capability families shared by every agent-facing command surface. */
+export type PmCommandCapabilityFamily = "workspace" | "intake" | "context" | "lifecycle" | "evidence" | "graph" | "quality" | "automation" | "extensions" | "internal";
 /** One command's canonical agent-surface visibility declaration. */
 export interface PmCommandVisibilityContract {
     /** Canonical command path. */
@@ -7,6 +9,13 @@ export interface PmCommandVisibilityContract {
     /** Minimum surface tier that advertises the command. */
     tier: PmCommandVisibilityTier;
 }
+/** Complete command capability contract with visibility and family ownership. */
+export interface PmCommandCapabilityContract extends PmCommandVisibilityContract {
+    /** Exactly one stable capability family used to group the command. */
+    family: PmCommandCapabilityFamily;
+}
+/** Resolve one command's stable capability family. */
+export declare function resolvePmCommandCapabilityFamily(command: string): PmCommandCapabilityFamily;
 /**
  * Canonical visibility contract for every built-in command.
  *
@@ -14,11 +23,15 @@ export interface PmCommandVisibilityContract {
  * surface. Internal worker/helper paths are appended below and never advertised
  * by normal help or completion projections.
  */
+export declare const PM_COMMAND_CAPABILITY_CONTRACTS: readonly PmCommandCapabilityContract[];
+/** Backward-compatible tier-only projection of the capability contract. */
 export declare const PM_COMMAND_VISIBILITY_CONTRACTS: readonly PmCommandVisibilityContract[];
 /** Resolve one command's declared tier; extension commands default to standard. */
 export declare function resolvePmCommandVisibilityTier(command: string, extensionTier?: PmCommandVisibilityTier): PmCommandVisibilityTier;
 /** Return commands visible at a requested tier, preserving contract order. */
 export declare function listPmCommandsForTier(tier: Exclude<PmCommandVisibilityTier, "internal">): string[];
+/** Return commands in one capability family, preserving contract order. */
+export declare function listPmCommandsForFamily(family: PmCommandCapabilityFamily): string[];
 /** MCP profile names accepted by the server and embedding hosts. */
 export type PmMcpToolProfile = "core" | "standard" | "full" | "custom";
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */

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]="6fc2cd04-2fe4-5a0e-944d-fab0f86509e2")}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]="dd74bc56-9971-59b9-8d2b-a6cc78b0a650")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -46,6 +46,92 @@ const STANDARD_COMMANDS = new Set([
     "schema",
     "test",
 ]);
+const COMMANDS_BY_FAMILY = Object.freeze({
+    workspace: new Set([
+        "config",
+        "gc",
+        "health",
+        "init",
+        "merge",
+        "profile",
+        "schema",
+        "telemetry",
+        "workspace",
+    ]),
+    intake: new Set(["copy", "create", "focus", "item", "restore"]),
+    context: new Set([
+        "activity",
+        "aggregate",
+        "context",
+        "ctx",
+        "duplicates",
+        "eval",
+        "get",
+        "help",
+        "list",
+        "list-all",
+        "list-blocked",
+        "list-canceled",
+        "list-closed",
+        "list-draft",
+        "list-in-progress",
+        "list-open",
+        "next",
+        "search",
+        "stats",
+    ]),
+    lifecycle: new Set([
+        "claim",
+        "close",
+        "close-many",
+        "close-task",
+        "delete",
+        "pause-task",
+        "release",
+        "start-task",
+        "update",
+        "update-many",
+    ]),
+    evidence: new Set([
+        "append",
+        "comments",
+        "docs",
+        "events",
+        "files",
+        "history",
+        "history-author-acknowledge",
+        "history-compact",
+        "history-redact",
+        "history-repair",
+        "learnings",
+        "notes",
+    ]),
+    graph: new Set(["deps", "graph", "plan"]),
+    quality: new Set([
+        "assurance",
+        "contracts",
+        "test",
+        "test-all",
+        "validate",
+    ]),
+    automation: new Set(["event", "meet", "remind"]),
+});
+const EXTENSION_COMMANDS = new Set([
+    "extension",
+    "install",
+    "package",
+    "packages",
+    "upgrade",
+]);
+/** Resolve one command's stable capability family. */
+export function resolvePmCommandCapabilityFamily(command) {
+    const normalized = command.trim().toLowerCase();
+    for (const [family, commands] of Object.entries(COMMANDS_BY_FAMILY)) {
+        if (commands.has(normalized))
+            return family;
+    }
+    return EXTENSION_COMMANDS.has(normalized) ? "extensions" : "internal";
+}
 /**
  * Canonical visibility contract for every built-in command.
  *
@@ -53,7 +139,7 @@ const STANDARD_COMMANDS = new Set([
  * surface. Internal worker/helper paths are appended below and never advertised
  * by normal help or completion projections.
  */
-export const PM_COMMAND_VISIBILITY_CONTRACTS = Object.freeze([
+export const PM_COMMAND_CAPABILITY_CONTRACTS = Object.freeze([
     ...PM_CORE_COMMAND_NAMES.map((command) => ({
         command,
         tier: CORE_COMMANDS.has(command)
@@ -61,24 +147,31 @@ export const PM_COMMAND_VISIBILITY_CONTRACTS = Object.freeze([
             : STANDARD_COMMANDS.has(command)
                 ? "standard"
                 : "full",
+        family: resolvePmCommandCapabilityFamily(command),
     })),
     {
         command: "completion-statuses",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "completion-tags",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "completion-types",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "test-runs-worker",
         tier: "internal",
+        family: "internal",
     },
 ]);
+/** Backward-compatible tier-only projection of the capability contract. */
+export const PM_COMMAND_VISIBILITY_CONTRACTS = PM_COMMAND_CAPABILITY_CONTRACTS;
 const TIER_ORDER = {
     core: 0,
     standard: 1,
@@ -95,6 +188,10 @@ export function listPmCommandsForTier(tier) {
     const maximum = TIER_ORDER[tier];
     return PM_COMMAND_VISIBILITY_CONTRACTS.filter((entry) => entry.tier !== "internal" && TIER_ORDER[entry.tier] <= maximum).map((entry) => entry.command);
 }
+/** Return commands in one capability family, preserving contract order. */
+export function listPmCommandsForFamily(family) {
+    return PM_COMMAND_CAPABILITY_CONTRACTS.filter((entry) => entry.family === family).map((entry) => entry.command);
+}
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */
 export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
     pm_append: "append",
@@ -217,17 +314,17 @@ export const PM_MCP_PROMPT_CONTRACTS = Object.freeze([
 ]);
 /** Render the generated command visibility reference used by docs drift gates. */
 export function renderPmCommandVisibilityMarkdown() {
-    const rows = PM_COMMAND_VISIBILITY_CONTRACTS.map(({ command, tier }) => `| \`${command}\` | ${tier} |`);
+    const rows = PM_COMMAND_CAPABILITY_CONTRACTS.map(({ command, tier, family }) => `| \`${command}\` | ${tier} | ${family} |`);
     return [
         "# Generated agent command surface",
         "",
-        "This file is generated from `PM_COMMAND_VISIBILITY_CONTRACTS`. Do not edit it manually.",
+        "This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.",
         "",
-        "| Command | Minimum visibility tier |",
-        "| --- | --- |",
+        "| Command | Minimum visibility tier | Capability family |",
+        "| --- | --- | --- |",
         ...rows,
         "",
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=6fc2cd04-2fe4-5a0e-944d-fab0f86509e2
+//# debugId=dd74bc56-9971-59b9-8d2b-a6cc78b0a650

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

@@ -10,7 +10,7 @@
  * 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]="cde15ba9-270e-5e05-baba-7dafbe1bd5da")}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]="9afc5057-afcd-5d6c-a4c1-c2883640fc50")}catch(e){}}();
 export const PM_COMMAND_ALIAS_CONTRACTS = [
     ...[
         ["fetch", "get"],
@@ -29,6 +29,22 @@ export const PM_COMMAND_ALIAS_CONTRACTS = [
         registration: "bootstrap",
         owner: "pm-pbyu",
     })),
+    ...[
+        ["extension list", "extension catalog"],
+        ["extension scaffold", "extension init"],
+        ["package list", "package catalog"],
+        ["package scaffold", "package init"],
+        ["packages list", "packages catalog"],
+        ["packages scaffold", "packages init"],
+    ].map(([alias, canonical]) => ({
+        alias,
+        canonical,
+        canonical_argv: canonical.split(" "),
+        lifecycle: "permanent",
+        hidden: false,
+        registration: "commander",
+        owner: "pm-ya7x55",
+    })),
     {
         alias: "list-all",
         canonical: "list",
@@ -67,4 +83,4 @@ export function renderPmCommandAliasMigrationHint(contract) {
     return `Deprecated command \`${contract.alias}\`; use \`pm ${contract.canonical_argv.join(" ")}\`.`;
 }
 //# sourceMappingURL=command-aliases.js.map
-//# debugId=cde15ba9-270e-5e05-baba-7dafbe1bd5da
+//# debugId=9afc5057-afcd-5d6c-a4c1-c2883640fc50

package/dist/sdk/cli-contracts/commander-mutation-options.js

@@ -1,6 +1,6 @@
 /** Creates commander option registration contracts using the validated operation inputs. */
 
-!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]="f7e87e15-b5f3-53ab-86e2-768e94d5d329")}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]="93ce68bd-3140-5361-a6d0-bc60c7304a29")}catch(e){}}();
 export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     {
         target: "title",
@@ -501,17 +501,29 @@ export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     },
     {
         target: "file",
-        keys: ["file"],
+        keys: ["file", "linkedFile"],
         option: "--file <value>",
         description: "Seed linked file entry (CSV/markdown pairs or - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-file <value>",
+                description: "Alias for --file (cross-surface name)",
+            },
+        ],
     },
     {
         target: "test",
-        keys: ["test"],
+        keys: ["test", "linkedTest"],
         option: "--test <value>",
         description: "Seed linked test entry (CSV/markdown pairs or - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-test <value>",
+                description: "Alias for --test (cross-surface name)",
+            },
+        ],
     },
     {
         target: "doc",
@@ -989,17 +1001,29 @@ export const UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     },
     {
         target: "file",
-        keys: ["file"],
+        keys: ["file", "linkedFile"],
         option: "--file <value>",
         description: "Append linked file path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-file <value>",
+                description: "Alias for --file (cross-surface name)",
+            },
+        ],
     },
     {
         target: "test",
-        keys: ["test"],
+        keys: ["test", "linkedTest"],
         option: "--test <value>",
         description: "Append linked test command=<value>,path=<value>,scope=<project|global>,timeout_seconds=<n>,pm_context_mode=<schema|tracker|auto> (also accepts markdown pairs and - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-test <value>",
+                description: "Alias for --test (cross-surface name)",
+            },
+        ],
     },
     {
         target: "doc",
@@ -1055,4 +1079,4 @@ export const UPDATE_COMMANDER_STRING_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_
 /** Public contract for update commander repeatable option contracts, shared by SDK and presentation-layer consumers. */
 export const UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.filter((entry) => entry.repeatable === true).map((entry) => ({ target: entry.target, keys: entry.keys }));
 //# sourceMappingURL=commander-mutation-options.js.map
-//# debugId=f7e87e15-b5f3-53ab-86e2-768e94d5d329
+//# debugId=93ce68bd-3140-5361-a6d0-bc60c7304a29

package/dist/sdk/cli-contracts/commander-types.js

@@ -1,6 +1,6 @@
 /** Public contract for list commander string option contracts, shared by SDK and presentation-layer 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]="3b9b9ebe-8d98-5983-8257-b7b77c7e6194")}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]="5f56c4ef-58e1-5cf6-a10e-dfa29b9ad3e8")}catch(e){}}();
 export const LIST_COMMANDER_STRING_OPTION_CONTRACTS = [
     { target: "status", keys: ["status"] },
     { target: "type", keys: ["type"] },
@@ -147,13 +147,14 @@ export function readFirstValueFromCommanderOptions(options, contract) {
 }
 /** Implements read string array from commander options for the public runtime surface of this module. */
 export function readStringArrayFromCommanderOptions(options, contract) {
+    const values = [];
     for (const key of contract.keys) {
         const candidate = options[key];
         if (Array.isArray(candidate)) {
-            return candidate;
+            values.push(...candidate.filter((value) => typeof value === "string"));
         }
     }
-    return undefined;
+    return values.length > 0 ? values : undefined;
 }
 //# sourceMappingURL=commander-types.js.map
-//# debugId=3b9b9ebe-8d98-5983-8257-b7b77c7e6194
+//# debugId=5f56c4ef-58e1-5cf6-a10e-dfa29b9ad3e8

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

@@ -1,3 +1,4 @@
+import { type PmPositionalActionContract } from "./grammar-contracts.js";
 /** A single CLI flag's contract: its canonical `--flag`, optional short form, aliases, value metadata, and repeat/list semantics. One source of truth shared by Commander registration, argv normalization, shell completion, and the `pm contracts` command so every surface agrees on the flag vocabulary. */
 export interface CliFlagContract {
     /** Value that configures or reports flag for this contract. */
@@ -214,6 +215,10 @@ export declare const CONTRACTS_FLAG_CONTRACTS: CliFlagContract[];
 export declare const COMPLETION_FLAG_CONTRACTS: CliFlagContract[];
 /** Deduplicates flag contracts by their `flag`/`short`/`aliases` identity, preserving first-seen order. Used when merging the shared subcommand-global flags into a command's own contracts so a flag declared by both surfaces is registered only once. */
 export declare function toUniqueFlagContracts(contracts: CliFlagContract[]): CliFlagContract[];
+/** Resolve every positional action's accepted flags against one parent contract. */
+export declare function resolvePmPositionalActionFlagContracts(actions?: readonly PmPositionalActionContract[]): Array<readonly [string, CliFlagContract[]]>;
+/** Validated positional action flag entries shared by registration and contracts. */
+export declare const PM_POSITIONAL_ACTION_FLAG_CONTRACTS: (readonly [string, CliFlagContract[]])[];
 /** Returns whether a normalized command path owns a concrete core flag-contract row. Surface-less commands such as `help` intentionally return false, while positional virtual paths such as `workspace snapshot create` return true. */
 export declare function hasSubcommandFlagContractsForCommand(commandName: string | undefined): boolean;
 /** Resolves the flag contracts a given command (or list/extension subcommand) accepts, merged with the shared subcommand-global flags. Returns the global set for unknown or surface-less commands so completion and validation degrade gracefully. */

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

@@ -7,9 +7,10 @@
  * 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]="1d9df714-a6dc-5dc3-b2ff-c9325f91a443")}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]="505e9b6b-a62a-5981-8862-619624246170")}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";
 function normalizeFlagAliasKey(flag) {
     if (!flag.startsWith("--")) {
         return flag;
@@ -1139,8 +1140,8 @@ export const CREATE_FLAG_CONTRACTS = [
     { flag: "--comment" },
     { flag: "--note" },
     { flag: "--learning" },
-    { flag: "--file" },
-    { flag: "--test" },
+    { flag: "--file", aliases: ["--linked-file"] },
+    { flag: "--test", aliases: ["--linked-test"] },
     { flag: "--doc" },
     { flag: "--unset" },
     { flag: "--clear-deps" },
@@ -1240,8 +1241,8 @@ export const UPDATE_FLAG_CONTRACTS = [
     { flag: "--comment" },
     { flag: "--note" },
     { flag: "--learning" },
-    { flag: "--file" },
-    { flag: "--test" },
+    { flag: "--file", aliases: ["--linked-file"] },
+    { flag: "--test", aliases: ["--linked-test"] },
     { flag: "--doc" },
     { flag: "--reminder" },
     { flag: "--event" },
@@ -1636,7 +1637,33 @@ export function toUniqueFlagContracts(contracts) {
     return unique;
 }
 function withSubcommandGlobalFlags(contracts) {
-    return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
+    const byCanonicalFlag = new Map();
+    for (const contract of [...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]) {
+        const canonicalFlag = normalizeFlagAliasKey(contract.flag);
+        const prior = byCanonicalFlag.get(canonicalFlag);
+        const { aliases: declaredAliases, ...contractWithoutAliases } = contract;
+        const aliases = normalizeUniqueStringList([
+            ...(declaredAliases ?? []),
+            ...(contract.flag === canonicalFlag ? [] : [contract.flag]),
+        ]).filter((alias) => alias !== canonicalFlag);
+        const normalizedContract = {
+            ...contractWithoutAliases,
+            flag: canonicalFlag,
+            ...(aliases.length > 0 ? { aliases } : {}),
+        };
+        const mergedAliases = normalizeUniqueStringList([
+            ...(prior?.aliases ?? []),
+            ...(normalizedContract.aliases ?? []),
+        ]);
+        byCanonicalFlag.set(canonicalFlag, prior === undefined
+            ? normalizedContract
+            : {
+                ...prior,
+                ...normalizedContract,
+                ...(mergedAliases.length > 0 ? { aliases: mergedAliases } : {}),
+            });
+    }
+    return withFlagAliasMetadata([...byCanonicalFlag.values()]);
 }
 const FIXED_STATUS_LIST_COMMAND_ALIASES = [
     "list-draft",
@@ -1648,6 +1675,43 @@ const FIXED_STATUS_LIST_COMMAND_ALIASES = [
 ];
 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) {
+        for (const spelling of [contract.flag, ...(contract.aliases ?? [])]) {
+            const matches = index.get(spelling) ?? [];
+            matches.push(contract);
+            index.set(spelling, matches);
+        }
+    }
+    return index;
+}
+const PLAN_FLAG_CONTRACT_INDEX = indexCliFlagContracts(PLAN_FLAG_CONTRACTS);
+const ASSURANCE_FLAG_CONTRACT_INDEX = indexCliFlagContracts(ASSURANCE_FLAG_CONTRACTS);
+const POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT = new Map([
+    ["assurance", ASSURANCE_FLAG_CONTRACT_INDEX],
+    ["plan", PLAN_FLAG_CONTRACT_INDEX],
+    ["workspace snapshot", indexCliFlagContracts(WORKSPACE_FLAG_CONTRACTS)],
+]);
+/** Resolve every positional action's accepted flags against one parent contract. */
+export function resolvePmPositionalActionFlagContracts(actions = PM_POSITIONAL_ACTION_CONTRACTS) {
+    return actions.map(({ command, parent, accepted_flags: acceptedFlags }) => {
+        const parentFlagIndex = POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT.get(parent);
+        if (!parentFlagIndex) {
+            throw new Error(`Positional action ${command} has no flag-contract index for ${parent}.`);
+        }
+        const selected = acceptedFlags.map((acceptedFlag) => {
+            const matches = parentFlagIndex.get(acceptedFlag) ?? [];
+            if (matches.length !== 1) {
+                throw new Error(`Positional action ${command} accepted flag ${acceptedFlag} does not resolve to exactly one ${parent} flag contract.`);
+            }
+            return matches[0];
+        });
+        return [command, selected];
+    });
+}
+/** Validated positional action flag entries shared by registration and contracts. */
+export const PM_POSITIONAL_ACTION_FLAG_CONTRACTS = resolvePmPositionalActionFlagContracts();
 // Single-token command (plus the `list`/`cal`/`ctx`/`templates` aliases) → its
 // dedicated flag-contract table. Lookups fall back to the subcommand-global set,
 // so tokens absent here (`reindex`, `help`, or any unknown command) degrade to
@@ -1723,6 +1787,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["telemetry", TELEMETRY_FLAG_CONTRACTS],
     ["health", HEALTH_FLAG_CONTRACTS],
     ["assurance", ASSURANCE_FLAG_CONTRACTS],
+    ...PM_POSITIONAL_ACTION_FLAG_CONTRACTS,
     ["validate", VALIDATE_FLAG_CONTRACTS],
     ["gc", GC_FLAG_CONTRACTS],
     ["stats", STATS_FLAG_CONTRACTS],
@@ -1751,6 +1816,7 @@ const EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND = new Map([
     ["reload", EXTENSION_RELOAD_FLAG_CONTRACTS],
     ["doctor", EXTENSION_DOCTOR_FLAG_CONTRACTS],
     ["catalog", EXTENSION_CATALOG_FLAG_CONTRACTS],
+    ["list", EXTENSION_CATALOG_FLAG_CONTRACTS],
     ["adopt", EXTENSION_ADOPT_FLAG_CONTRACTS],
     ["adopt-all", EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],
     ["activate", EXTENSION_ACTIVATE_FLAG_CONTRACTS],
@@ -1776,11 +1842,12 @@ export function hasSubcommandFlagContractsForCommand(commandName) {
         lifecycleSubcommand !== undefined &&
         extraParts.length === 0 &&
         (lifecycleSubcommand === "init" ||
+            lifecycleSubcommand === "scaffold" ||
             EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND.has(lifecycleSubcommand)));
 }
 /** Resolves the flag contracts an `extension`/`package <subcommand>` lifecycle invocation accepts. `init` carries the package-only `--declarative` flag, so `package`/`packages init` resolve to the package init table while `extension init` resolves to the extension init table; every other lifecycle subcommand shares one table, and an unknown subcommand falls back to globals-only. */
 function resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand) {
-    if (lifecycleSubcommand === "init") {
+    if (lifecycleSubcommand === "init" || lifecycleSubcommand === "scaffold") {
         // `--declarative` is package-only, so `package init` / `packages init` carry it.
         return rootCommand === "extension"
             ? EXTENSION_INIT_FLAG_CONTRACTS
@@ -1825,4 +1892,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=1d9df714-a6dc-5dc3-b2ff-c9325f91a443
+//# debugId=505e9b6b-a62a-5981-8862-619624246170