@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/dist/sdk/cli-contracts.js

@@ -1,5 +1,5 @@
 
-!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]="8071fd9d-649a-5fce-b342-84b11066d559")}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]="969b5bd2-e7de-5db8-bef2-6748675a100c")}catch(e){}}();
 export { EXECUTABLE_COMMAND_ALIASES } from "./cli-contracts/command-aliases.js";
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "./cli-contracts/commander-types.js";
 export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
@@ -9,9 +9,9 @@ export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEAT
 // keep importing everything from "./cli-contracts.js" unchanged.
 export { PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
 export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, } from "./cli-contracts/tool-option-contracts.js";
-export { withFlagAliasMetadata, compactFlagAliasContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
+export { withFlagAliasMetadata, compactFlagAliasContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
 export { buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, resolvePmToolCustomFieldCollision, CLOSE_ACTION_OPTION_KEYS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, _testOnlyCliContracts, } from "./cli-contracts/tool-schema.js";
 export { analyzeSdkCliParameterCompleteness, } from "./cli-contracts/completeness.js";
 export { PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, resolvePmCommandOutputBudget, } from "./cli-contracts/agent-output-contracts.js";
 //# sourceMappingURL=cli-contracts.js.map
-//# debugId=8071fd9d-649a-5fce-b342-84b11066d559
+//# debugId=969b5bd2-e7de-5db8-bef2-6748675a100c

package/dist/sdk/completion.js

@@ -4,7 +4,7 @@
  * Implements the pm completion 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]="6c9648d7-ab14-5e0d-8793-86ae13643fa6")}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]="381bfd99-bd9b-5f8f-9783-65c2bf2cd810")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
@@ -608,7 +608,7 @@ export function generateBashScript(itemTypes = [], tags = [], eagerTagExpansion
         `      COMPREPLY=(${compgen("--add --stdin --file --edit --delete --limit --full-history --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    files)",
-        `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("discover lookup --add --add-glob --remove --migrate --list --apply --note --append-stable --validate-paths --scope --limit --offset --no-truncate --strict-read --explain --lines --decision-depth --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    docs)",
         `      COMPREPLY=(${compgen("--add --add-glob --remove --migrate --note --validate-paths --author --message --force --json --quiet --no-changed-fields --pm-path --path --no-extensions --no-pager --profile --help")})`,
@@ -1412,6 +1412,9 @@ ${zshSearchRuntimeFieldFlags}            '--json[Output JSON]' \\
             '--offset[Skip the first lookup matches]:number' \\
             '--no-truncate[Return every lookup match]' \\
             '--strict-read[Require authoritative source reads]' \\
+            '--explain[Include ranked source-to-work rationale]' \\
+            '--lines[Attribute an inclusive source line range]:start_end' \\
+            '--decision-depth[Maximum governing-decision relationship depth]:number' \\
             '--author[Mutation author]:author' \\
             '--message[History message]:message' \\
             '--force[Force override]' \\
@@ -2137,6 +2140,9 @@ complete -c pm -n '__fish_seen_subcommand_from files' -l limit -d 'Maximum looku
 complete -c pm -n '__fish_seen_subcommand_from files' -l offset -d 'Skip the first lookup matches' -r
 complete -c pm -n '__fish_seen_subcommand_from files' -l no-truncate -d 'Return every lookup match'
 complete -c pm -n '__fish_seen_subcommand_from files' -l strict-read -d 'Require authoritative source reads'
+complete -c pm -n '__fish_seen_subcommand_from files' -l explain -d 'Include ranked source-to-work rationale'
+complete -c pm -n '__fish_seen_subcommand_from files' -l lines -d 'Attribute an inclusive source line range' -r
+complete -c pm -n '__fish_seen_subcommand_from files' -l decision-depth -d 'Maximum governing-decision relationship depth' -r
 
 
 # search flags
@@ -2747,4 +2753,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=6c9648d7-ab14-5e0d-8793-86ae13643fa6
+//# debugId=381bfd99-bd9b-5f8f-9783-65c2bf2cd810

package/dist/sdk/config.js

@@ -4,7 +4,7 @@
  * Implements the pm config 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]="2a186a29-9d21-5ebe-9c66-3e889253b15b")}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]="a9a8d99c-df4e-55b3-81f5-27124d598c5f")}catch(e){}}();
 import { pathExists } from "../core/fs/fs-utils.js";
 import { resolveConfigPositionalValue, } from "../core/config/positional-value.js";
 import { NESTED_SETTING_DESCRIPTORS, parseNestedSettingValue, readNestedSettingValue, resolveNestedSettingDescriptor, writeNestedSettingValue, } from "../core/config/nested-settings.js";
@@ -16,6 +16,7 @@ import { buildInvalidTypeError } from "../core/schema/item-types-file.js";
 import { resolveItemTypesFilePath } from "../core/schema/runtime-schema.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 import { readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
@@ -181,7 +182,12 @@ function normalizeAction(value) {
         value === "export") {
         return value;
     }
-    throw new PmCliError(`Invalid config action "${value}". Allowed: get, set, list, export`, EXIT_CODE.USAGE);
+    throw createUnknownSubcommandError({
+        command_path: "config",
+        token: value.trim() || "<empty>",
+        allowed: ["export", "get", "list", "set"],
+        token_kind: "action",
+    });
 }
 function normalizeKey(value) {
     const key = CONFIG_KEY_BY_ALIAS[value];
@@ -1091,4 +1097,4 @@ export const _testOnlyConfigCommand = {
     normalizeWarnings,
 };
 //# sourceMappingURL=config.js.map
-//# debugId=2a186a29-9d21-5ebe-9c66-3e889253b15b
+//# debugId=a9a8d99c-df4e-55b3-81f5-27124d598c5f

package/dist/sdk/context/semantic-session-attribution.d.ts

@@ -0,0 +1,32 @@
+import { type AgentSemanticAttribution } from "../../core/session/session-state.js";
+import { readSettings } from "../../core/store/settings.js";
+/** Resolve an item's canonical parent lineage under a strict depth bound. */
+export declare function resolveSemanticLineageIds(pmRoot: string, settings: Awaited<ReturnType<typeof readSettings>>, itemId: string): Promise<string[]>;
+/** Record one successful claim and its bounded canonical lineage. */
+export declare function recordClaimSemanticAttribution(params: {
+    pmRoot: string;
+    settings: Awaited<ReturnType<typeof readSettings>>;
+    principal: string;
+    itemId: string;
+}): Promise<void>;
+/** Remove one released claim from the active semantic workset. */
+export declare function recordReleaseSemanticAttribution(params: {
+    pmRoot: string;
+    principal: string;
+    itemId: string;
+}): Promise<void>;
+/** Set or clear focused semantic work with canonical lineage evidence. */
+export declare function recordFocusSemanticAttribution(params: {
+    pmRoot: string;
+    settings: Awaited<ReturnType<typeof readSettings>>;
+    principal: string;
+    itemId?: string;
+}): Promise<void>;
+/** Public constants used by scale and negative-control tests. */
+export declare const SEMANTIC_ATTRIBUTION_LIMITS: {
+    readonly lineage_depth: 16;
+    readonly active_items: 64;
+    readonly evidence_rows: 32;
+};
+/** Convert bounded claim/focus evidence into normalized context affinity. */
+export declare function semanticAttributionAffinity(attribution: AgentSemanticAttribution | undefined): Readonly<Record<string, number>> | undefined;

package/dist/sdk/context/semantic-session-attribution.js

@@ -0,0 +1,83 @@
+/**
+ * @module sdk/semantic-session-attribution
+ *
+ * Maintains bounded claimed/focused lineage evidence used by automatic
+ * mutation provenance without scanning history or retaining prompt content.
+ */
+
+!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]="97c1e310-3cd9-5846-a54c-d019b0351541")}catch(e){}}();
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { recordClaimedWorkAttribution, recordFocusedWorkAttribution, releaseClaimedWorkAttribution, } from "../../core/session/session-state.js";
+import { locateItem, readLocatedItem } from "../../core/store/item-store.js";
+const MAX_SEMANTIC_LINEAGE_DEPTH = 16;
+/** Resolve an item's canonical parent lineage under a strict depth bound. */
+export async function resolveSemanticLineageIds(pmRoot, settings, itemId) {
+    const typeToFolder = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations()).type_to_folder;
+    const lineage = [];
+    const seen = new Set();
+    let cursor = itemId;
+    while (cursor && lineage.length < MAX_SEMANTIC_LINEAGE_DEPTH) {
+        const normalized = cursor.trim().toLowerCase();
+        if (!normalized || seen.has(normalized))
+            break;
+        seen.add(normalized);
+        const located = await locateItem(pmRoot, cursor, settings.id_prefix, settings.item_format, typeToFolder);
+        if (!located)
+            break;
+        const loaded = await readLocatedItem(located, { schema: settings.schema });
+        lineage.push(loaded.document.metadata.id);
+        cursor = loaded.document.metadata.parent;
+    }
+    return lineage;
+}
+/** Record one successful claim and its bounded canonical lineage. */
+export async function recordClaimSemanticAttribution(params) {
+    await recordClaimedWorkAttribution({
+        pmRoot: params.pmRoot,
+        principal: params.principal,
+        itemId: params.itemId,
+        lineageIds: await resolveSemanticLineageIds(params.pmRoot, params.settings, params.itemId),
+    });
+}
+/** Remove one released claim from the active semantic workset. */
+export async function recordReleaseSemanticAttribution(params) {
+    await releaseClaimedWorkAttribution(params);
+}
+/** Set or clear focused semantic work with canonical lineage evidence. */
+export async function recordFocusSemanticAttribution(params) {
+    await recordFocusedWorkAttribution({
+        pmRoot: params.pmRoot,
+        principal: params.principal,
+        ...(params.itemId
+            ? {
+                itemId: params.itemId,
+                lineageIds: await resolveSemanticLineageIds(params.pmRoot, params.settings, params.itemId),
+            }
+            : {}),
+    });
+}
+/** Public constants used by scale and negative-control tests. */
+export const SEMANTIC_ATTRIBUTION_LIMITS = {
+    lineage_depth: MAX_SEMANTIC_LINEAGE_DEPTH,
+    active_items: 64,
+    evidence_rows: 32,
+};
+/** Convert bounded claim/focus evidence into normalized context affinity. */
+export function semanticAttributionAffinity(attribution) {
+    if (!attribution)
+        return undefined;
+    const affinity = {};
+    for (const itemId of attribution.active_item_ids)
+        affinity[itemId] = 1;
+    if (attribution.focused_item_id)
+        affinity[attribution.focused_item_id] = 1;
+    for (const evidence of attribution.evidence) {
+        const lineage = /^lineage:(.+)$/u.exec(evidence)?.[1];
+        if (lineage && affinity[lineage] === undefined)
+            affinity[lineage] = 0.75;
+    }
+    return Object.keys(affinity).length > 0 ? affinity : undefined;
+}
+//# sourceMappingURL=semantic-session-attribution.js.map
+//# debugId=97c1e310-3cd9-5846-a54c-d019b0351541

package/dist/sdk/context-intent-runtime.js

@@ -6,9 +6,10 @@
  * SDK entrypoint.
  */
 
-!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]="55ecd7ff-0047-5fd1-9f6f-f45602fce1bb")}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]="7ba0243e-98d1-5aef-bd47-54f0b630be58")}catch(e){}}();
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { runWithContextIntentContracts, } from "./context-intent-contracts.js";
 /** Conventional workspace declaration file relative to the tracker root. */
 export const PM_CONTEXT_INTENTS_FILE = "context-intents.json";
@@ -56,9 +57,11 @@ export async function readWorkspaceContextIntentContracts(pmRoot) {
         source = await readFile(declarationPath, "utf8");
     }
     catch (error) {
-        if (isRecord(error) &&
-            typeof error.code === "string" &&
-            error.code === "ENOENT") {
+        // Absent declarations are the norm. `ENOTDIR` counts as absent too: when
+        // the tracker root is a regular file the declaration cannot exist, and the
+        // authoritative root guard downstream owns that refusal — this optional
+        // read must not pre-empt it with a raw runtime fault.
+        if (isFileAbsentError(error)) {
             return [];
         }
         throw error;
@@ -107,4 +110,4 @@ export async function runWithDiscoveredContextIntentContracts(options, run) {
     return await runWithContextIntentContracts(layers, run);
 }
 //# sourceMappingURL=context-intent-runtime.js.map
-//# debugId=55ecd7ff-0047-5fd1-9f6f-f45602fce1bb
+//# debugId=7ba0243e-98d1-5aef-bd47-54f0b630be58

package/dist/sdk/context-signal-store.d.ts

@@ -52,7 +52,41 @@ export interface ContextSignalStoreReadResult {
     cache_status: "fresh" | "rebuilt";
     /** Non-fatal recovery diagnostics. */
     warnings: readonly string[];
+    /** Actionable meanings and executable recovery commands for every warning. */
+    warning_details?: readonly ContextSignalStoreWarningDetail[];
 }
+/** Stable recovery contract for one context signal-store warning. */
+export interface ContextSignalStoreWarningDetail {
+    /** Machine-readable warning code also present in `warnings`. */
+    code: "context_signal_store_invalid" | "context_signal_store_stale" | "context_signal_store_write_failed";
+    /** Bounded explanation of the observed derived-state condition. */
+    meaning: string;
+    /** Safe executable command that retries or confirms recovery. */
+    recovery_command: "pm context";
+    /** Expected observable effect of the recovery command. */
+    recovery_effect: string;
+}
+/** Canonical actionable contracts shared by CLI, SDK, MCP, and package hosts. */
+export declare const CONTEXT_SIGNAL_STORE_WARNING_DETAILS: {
+    readonly context_signal_store_invalid: {
+        readonly code: "context_signal_store_invalid";
+        readonly meaning: "The persisted context-signal snapshot was unreadable or invalid and was rebuilt from authoritative items.";
+        readonly recovery_command: "pm context";
+        readonly recovery_effect: "Re-read context and confirm the rebuilt snapshot can be loaded without the warning.";
+    };
+    readonly context_signal_store_stale: {
+        readonly code: "context_signal_store_stale";
+        readonly meaning: "The persisted context-signal snapshot did not match the authoritative cursor or item corpus and was rebuilt.";
+        readonly recovery_command: "pm context";
+        readonly recovery_effect: "Re-read context and confirm the rebuilt snapshot is now fresh.";
+    };
+    readonly context_signal_store_write_failed: {
+        readonly code: "context_signal_store_write_failed";
+        readonly meaning: "Context signals were rebuilt in memory, but the derived snapshot could not be persisted.";
+        readonly recovery_command: "pm context";
+        readonly recovery_effect: "Retry the derived snapshot write and confirm the warning clears after storage access is restored.";
+    };
+};
 /** Workspace-bound feature-store options used by CLI, MCP, and SDK readers. */
 export interface ReadWorkspaceContextSignalsOptions extends BuildItemContextRelevanceCandidatesOptions {
     /** Tracker root containing rebuildable runtime state. */

package/dist/sdk/context-signal-store.js

@@ -6,7 +6,7 @@
  * history, while stale, absent, or corrupt snapshots rebuild transparently.
  */
 
-!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]="a502be8f-57da-53c2-8de0-118a15688d93")}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]="2a0f64cf-f6a4-5304-921d-c83b98d3a31f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -24,6 +24,27 @@ const STORED_CONTEXT_SIGNAL_NAMES = [
     "risk_pressure",
     "knowledge_density",
 ];
+/** Canonical actionable contracts shared by CLI, SDK, MCP, and package hosts. */
+export const CONTEXT_SIGNAL_STORE_WARNING_DETAILS = {
+    context_signal_store_invalid: {
+        code: "context_signal_store_invalid",
+        meaning: "The persisted context-signal snapshot was unreadable or invalid and was rebuilt from authoritative items.",
+        recovery_command: "pm context",
+        recovery_effect: "Re-read context and confirm the rebuilt snapshot can be loaded without the warning.",
+    },
+    context_signal_store_stale: {
+        code: "context_signal_store_stale",
+        meaning: "The persisted context-signal snapshot did not match the authoritative cursor or item corpus and was rebuilt.",
+        recovery_command: "pm context",
+        recovery_effect: "Re-read context and confirm the rebuilt snapshot is now fresh.",
+    },
+    context_signal_store_write_failed: {
+        code: "context_signal_store_write_failed",
+        meaning: "Context signals were rebuilt in memory, but the derived snapshot could not be persisted.",
+        recovery_command: "pm context",
+        recovery_effect: "Retry the derived snapshot write and confirm the warning clears after storage access is restored.",
+    },
+};
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -245,6 +266,7 @@ export class ContextSignalStore {
             })),
             cache_status: fresh ? "fresh" : "rebuilt",
             warnings,
+            warning_details: warnings.map((warning) => CONTEXT_SIGNAL_STORE_WARNING_DETAILS[warning]),
         };
     }
 }
@@ -288,4 +310,4 @@ export async function readWorkspaceContextSignals(items, options) {
     return store.readOrRebuild(items, { ...options, sourceCursor, source });
 }
 //# sourceMappingURL=context-signal-store.js.map
-//# debugId=a502be8f-57da-53c2-8de0-118a15688d93
+//# debugId=2a0f64cf-f6a4-5304-921d-c83b98d3a31f

package/dist/sdk/core-governance.d.ts

@@ -5,5 +5,7 @@
  * exposed by both the focused core entrypoint and the complete SDK barrel.
  */
 export { AGENT_PROVENANCE_DIMENSIONS, BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, diagnoseAgentIdentity, detectAgentIdentity, detectHarnessIdentity, readAuthorEnvironment, registerHarnessSignalDescriptors, resolveAuthorIdentity, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, writeAuthorEnvironment, type AgentClientInfo, type AgentModelSource, type AgentProvenance, type AgentProvenanceAbsenceReason, type AgentProvenanceObservation, type AgentProvenanceOutcome, type AuthorSource, type DetectedAgentIdentity, type DiagnosedAgentIdentity, type HarnessDetectionSignals, type HarnessSignalDescriptor, type ResolvedAuthorIdentity, } from "../core/shared/author.js";
-export { analyzeAgentProvenanceDescriptorCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, type AgentEpisodeGroup, type AgentModelProvenanceCoverage, type AgentProvenanceDimensionCoverage, type AgentProvenanceDescriptorCoverage, } from "./provenance.js";
+export { SEMANTIC_ATTRIBUTION_LIMITS, recordClaimSemanticAttribution, recordFocusSemanticAttribution, recordReleaseSemanticAttribution, resolveSemanticLineageIds, semanticAttributionAffinity, } from "./context/semantic-session-attribution.js";
+export { explainSourceTraceability, parseSourceLineRange, type SourceDecisionPath, type SourceLineRange, type SourceTraceabilityEvidence, type SourceTraceabilityExplanation, type SourceTraceabilityRationale, type SourceTraceabilityReceipt, } from "./traceability/source-traceability.js";
+export { analyzeAgentProvenanceDescriptorCoverage, evaluateSemanticAttributionCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, type AgentEpisodeGroup, type AgentModelProvenanceCoverage, type AgentProvenanceDimensionCoverage, type AgentProvenanceDescriptorCoverage, type AgentSemanticAttributionCoverage, type AgentSemanticAttributionCoverageGate, } from "./provenance.js";
 export { analyzeSdkCliParameterCompleteness, type SdkCliActionParameterCoverage, type SdkCliCompletenessContractSource, type SdkCliParameterCoverageEntry, type SdkCliParameterDisposition, } from "./cli-contracts.js";

package/dist/sdk/core-governance.js

@@ -5,9 +5,11 @@
  * exposed by both the focused core entrypoint and the complete SDK barrel.
  */
 
-!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]="7442357d-52b9-5461-9ac4-3acd898334da")}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]="d19cfa31-a02f-53a7-8685-5d169d6e051d")}catch(e){}}();
 export { AGENT_PROVENANCE_DIMENSIONS, BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, diagnoseAgentIdentity, detectAgentIdentity, detectHarnessIdentity, readAuthorEnvironment, registerHarnessSignalDescriptors, resolveAuthorIdentity, runWithHarnessDetectionSignals, runWithWorkspaceHarnessSignalDescriptors, writeAuthorEnvironment, } from "../core/shared/author.js";
-export { analyzeAgentProvenanceDescriptorCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, } from "./provenance.js";
+export { SEMANTIC_ATTRIBUTION_LIMITS, recordClaimSemanticAttribution, recordFocusSemanticAttribution, recordReleaseSemanticAttribution, resolveSemanticLineageIds, semanticAttributionAffinity, } from "./context/semantic-session-attribution.js";
+export { explainSourceTraceability, parseSourceLineRange, } from "./traceability/source-traceability.js";
+export { analyzeAgentProvenanceDescriptorCoverage, evaluateSemanticAttributionCoverage, groupHistoryByEpisode, resolveHistoryEpisodeGroupIdentity, summarizeAgentProvenance, summarizeAgentModelProvenance, } from "./provenance.js";
 export { analyzeSdkCliParameterCompleteness, } from "./cli-contracts.js";
 //# sourceMappingURL=core-governance.js.map
-//# debugId=7442357d-52b9-5461-9ac4-3acd898334da
+//# debugId=d19cfa31-a02f-53a7-8685-5d169d6e051d

package/dist/sdk/core.d.ts

@@ -3,7 +3,7 @@
  *
  * Provides the stable item lifecycle client and universal project data types.
  */
-export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
+export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AssuranceActionInput, type AssuranceActionResult, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
 export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";

package/dist/sdk/core.js

@@ -4,11 +4,11 @@
  * Provides the stable item lifecycle client and universal project data types.
  */
 
-!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]="54d31df7-e708-585d-9fb2-3c5ddfcc6138")}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]="c2f56389-6238-5b5c-add8-00296fe401b6")}catch(e){}}();
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
 export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
 export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 //# sourceMappingURL=core.js.map
-//# debugId=54d31df7-e708-585d-9fb2-3c5ddfcc6138
+//# debugId=c2f56389-6238-5b5c-add8-00296fe401b6

package/dist/sdk/dependency-flag-validation.d.ts

@@ -1,4 +1,4 @@
-import type { Dependency } from "../types/index.js";
+import type { Dependency, ItemFormat } from "../types/index.js";
 import { type RelationshipKindRegistry } from "./relationships.js";
 /** Reject malformed shorthand before item-id prefix normalization can create a dangling graph node. */
 export declare function assertValidBareDependencyFlagValue(value: string, structured: boolean): void;
@@ -7,3 +7,17 @@ export declare function assertValidBareDependencyFlagValue(value: string, struct
  * ontology before a create or update mutation writes item or history state.
  */
 export declare function assertDependencyEdgesAllowed(holderId: string, dependencies: readonly Dependency[] | undefined, registry?: RelationshipKindRegistry): void;
+/**
+ * Resolve every newly supplied local dependency before a mutation commits.
+ * Explicit external provenance bypasses workspace lookup, while the opt-in
+ * unresolved mode returns durable warning tokens instead of pretending that
+ * the graph edge resolved successfully.
+ */
+export declare function assertDependencyTargetsResolvable(params: {
+    pmRoot: string;
+    dependencies: readonly Dependency[] | undefined;
+    idPrefix: string;
+    itemFormat: ItemFormat;
+    typeToFolder: Record<string, string>;
+    allowUnresolved?: boolean;
+}): Promise<string[]>;

package/dist/sdk/dependency-flag-validation.js

@@ -1,9 +1,11 @@
 /** @module cli/commands/dependency-flag-validation */
 
-!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]="1c1314f1-b54f-562c-b6f0-950fcac4c9cc")}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]="e7cd6092-ed18-52ea-94a0-03bed42eb858")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { toErrorMessage } from "../core/shared/primitives.js";
+import { locateItem } from "../core/store/item-store.js";
+import { isExternalDependencySourceKind } from "./dependency-provenance.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "./graph/assembly.js";
 import { assertRelationshipEdgeAllowed, } from "./relationships.js";
 /** Reject malformed shorthand before item-id prefix normalization can create a dangling graph node. */
@@ -29,5 +31,55 @@ export function assertDependencyEdgesAllowed(holderId, dependencies, registry =
         }
     }
 }
+/**
+ * Resolve every newly supplied local dependency before a mutation commits.
+ * Explicit external provenance bypasses workspace lookup, while the opt-in
+ * unresolved mode returns durable warning tokens instead of pretending that
+ * the graph edge resolved successfully.
+ */
+export async function assertDependencyTargetsResolvable(params) {
+    const localTargets = [
+        ...new Set((params.dependencies ?? [])
+            .filter((dependency) => !isExternalDependencySourceKind(dependency.source_kind))
+            .map((dependency) => dependency.id)),
+    ];
+    const resolutions = await Promise.all(localTargets.map(async (target) => ({
+        target,
+        located: await locateItem(params.pmRoot, target, params.idPrefix, params.itemFormat, params.typeToFolder),
+    })));
+    const targets = resolutions
+        .filter(({ located }) => located === null)
+        .map(({ target }) => target)
+        .sort((left, right) => (left < right ? -1 : 1));
+    if (targets.length === 0) {
+        return [];
+    }
+    if (params.allowUnresolved === true) {
+        return targets.map((target) => `dependency_target_unresolved:${target}`);
+    }
+    throw new PmCliError(`Dependency target${targets.length === 1 ? "" : "s"} not found: ${targets.join(", ")}`, EXIT_CODE.NOT_FOUND, {
+        code: "dependency_target_not_found",
+        reason: "unresolved_local_dependency",
+        required: "Every local dependency target must exist before the edge is committed.",
+        why: "Fail-fast target resolution prevents dangling graph nodes and preserves reliable traversal semantics.",
+        unresolved_targets: targets,
+        examples: [
+            "--dep id=<existing-item-id>,kind=related",
+            "--dep id=<external-id>,kind=related,source_kind=external",
+            "--allow-unresolved-deps --dep id=<future-item-id>,kind=related",
+        ],
+        nextSteps: [
+            `Create or correct ${targets.length === 1 ? "the target" : "the targets"}, then retry the mutation.`,
+            "Use source_kind=external for a cross-workspace reference.",
+            "Use --allow-unresolved-deps only when the dangling local edge is intentional.",
+        ],
+        recovery: {
+            recovery_mode: "compact",
+            missing: targets,
+            suggested_flags: ["--allow-unresolved-deps"],
+            suggested_retry: `pm search "${targets[0]}" --limit 10`,
+        },
+    });
+}
 //# sourceMappingURL=dependency-flag-validation.js.map
-//# debugId=1c1314f1-b54f-562c-b6f0-950fcac4c9cc
+//# debugId=e7cd6092-ed18-52ea-94a0-03bed42eb858

package/dist/sdk/error-code-catalog.d.ts

@@ -8,6 +8,17 @@
 export type PmErrorCodeStability = "provisional" | "stable";
 /** Semantic process-exit class shared by shell and SDK consumers. */
 export type PmErrorCodeClass = "generic_failure" | "usage" | "not_found" | "conflict" | "dependency_failed";
+/** One externally observable refusal state and its executable entrypoint probe. */
+export interface PmRefusalStateContract {
+    /** Stable semantic state owned by the error code. */
+    state: string;
+    /** Stable probe identifier implemented by the entrypoint conformance suite. */
+    probe_id: string;
+    /** Public command roots through which the state must remain reachable. */
+    entrypoints: string[];
+    /** Exit class expected when the probe reaches the state. */
+    expected_exit_class: PmErrorCodeClass;
+}
 /** Stable shell exit-code taxonomy shared by every structured error. */
 export declare const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS: readonly [{
     readonly exit_code: 1;
@@ -47,6 +58,8 @@ export interface PmErrorCodeContract {
     canonical_code?: string;
     /** Stable compatibility spellings that resolve to this canonical code. */
     aliases?: string[];
+    /** Observable states this code claims, each backed by a real-entrypoint probe. */
+    owned_states?: PmRefusalStateContract[];
 }
 /** Validate, normalize, sort, and freeze an error-code catalog. */
 export declare function definePmErrorCodeCatalog(declarations: readonly PmErrorCodeContract[]): readonly PmErrorCodeContract[];

package/dist/sdk/error-code-catalog.js

@@ -6,7 +6,7 @@
  */
 /** Stable shell exit-code taxonomy shared by every structured error. */
 
-!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]="393243a5-dd90-52c1-a9c1-588fd33f8b6a")}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]="c76fa303-6672-5c1e-9cf5-3a08bd3a7814")}catch(e){}}();
 export const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS = [
     { exit_code: 1, class: "generic_failure" },
     { exit_code: 2, class: "usage" },
@@ -21,6 +21,34 @@ function normalizeContractList(values) {
         ...new Set(values.map((value) => value.trim()).filter(Boolean)),
     ].sort();
 }
+function normalizeOwnedStates(states) {
+    if (!states)
+        return [];
+    const seenStates = new Set();
+    const seenProbes = new Set();
+    return states
+        .map((state) => {
+        const normalizedState = state.state.trim();
+        const probeId = state.probe_id.trim();
+        const entrypoints = normalizeContractList(state.entrypoints);
+        if (!/^[a-z][a-z0-9_]*$/.test(normalizedState) ||
+            !/^[a-z][a-z0-9-]*$/.test(probeId) ||
+            entrypoints.length === 0 ||
+            seenStates.has(normalizedState) ||
+            seenProbes.has(probeId)) {
+            throw new TypeError("Invalid pm refusal state contract");
+        }
+        seenStates.add(normalizedState);
+        seenProbes.add(probeId);
+        return {
+            state: normalizedState,
+            probe_id: probeId,
+            entrypoints,
+            expected_exit_class: state.expected_exit_class,
+        };
+    })
+        .sort((left, right) => left.state.localeCompare(right.state));
+}
 function isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases) {
     return ![
         [1, 2, 3, 4, 5].includes(declaration.exit_code),
@@ -86,9 +114,13 @@ export function definePmErrorCodeCatalog(declarations) {
         const emittingCommands = normalizeContractList(declaration.emitting_commands);
         const canonicalCode = (declaration.canonical_code ?? code).trim();
         const aliases = normalizeContractList(declaration.aliases ?? []);
+        const ownedStates = normalizeOwnedStates(declaration.owned_states);
         if (!isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases)) {
             throw new TypeError(`Invalid pm error code contract: ${code}`);
         }
+        if (ownedStates.some((state) => state.expected_exit_class !== declaration.class)) {
+            throw new TypeError(`Invalid pm refusal state exit class: ${code}`);
+        }
         return Object.freeze({
             ...declaration,
             code,
@@ -98,6 +130,7 @@ export function definePmErrorCodeCatalog(declarations) {
             emitting_commands: emittingCommands,
             canonical_code: canonicalCode,
             aliases,
+            owned_states: ownedStates,
         });
     });
     validateErrorCodeAliases(normalized);
@@ -118,4 +151,4 @@ export function resolvePmErrorCodeContract(code, catalog) {
     return contract;
 }
 //# sourceMappingURL=error-code-catalog.js.map
-//# debugId=393243a5-dd90-52c1-a9c1-588fd33f8b6a
+//# debugId=c76fa303-6672-5c1e-9cf5-3a08bd3a7814