@unbrained/pm-cli 2026.8.10 → 2026.8.11

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/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/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

package/dist/sdk/extension.js

@@ -4,7 +4,7 @@
  * Implements the pm extension 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]="f4b47053-cc05-51f2-b5cb-cc6dba3365c2")}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]="8b0fbe09-2221-5b8e-8712-90a83df19306")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
@@ -20,6 +20,7 @@ import { nowIso } from "../core/shared/time.js";
 import { resolveGlobalPmRoot, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings, writeSettings } from "../core/store/settings.js";
 import { quoteCommandArg, renderPmCommand } from "./command-line.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { ensureTypeFolderScaffold } from "./schema.js";
 // Cohesive helper groups now live in ./extension/* sibling modules. They are
 // imported for the command wiring that stays here and re-exported below so
@@ -321,21 +322,21 @@ const buildUnknownLifecycleActionError = (target, options) => {
         return new PmCliError(`One action flag is required. Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}. Bare \`pm package\` and \`pm extension\` default to --explore.`, EXIT_CODE.USAGE);
     }
     const command = `pm ${noun} ${suggestion.flag}`;
-    return new PmCliError(`Unknown ${noun} lifecycle action "${target}". Did you mean "${suggestion.flag}"?`, EXIT_CODE.USAGE, {
-        code: "unknown_lifecycle_action",
-        required: `Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}.`,
-        examples: [command, `pm ${noun} --help`],
-        recovery: {
-            attempted_command: `pm ${noun} ${target}`,
-            suggested_retry: command,
-            fallback_candidates: [
-                {
-                    source: "lifecycle_action",
-                    command,
-                    reason: `nearest lifecycle action for "${target}"`,
-                },
-            ],
-        },
+    return createUnknownSubcommandError({
+        command_path: noun,
+        display_name: `${noun} lifecycle`,
+        token_kind: "action",
+        token: target,
+        allowed: Object.keys(IMPLICIT_EXTENSION_ACTIONS),
+        retry_command: command,
+        message_suffix: `. Did you mean "${suggestion.flag}"?`,
+        fallback_candidates: [
+            {
+                source: "lifecycle_action",
+                command,
+                reason: `nearest lifecycle action for "${target}"`,
+            },
+        ],
     });
 };
 // Maps each boolean action flag to the lifecycle action it selects. `scaffold`
@@ -2190,4 +2191,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=f4b47053-cc05-51f2-b5cb-cc6dba3365c2
+//# debugId=8b0fbe09-2221-5b8e-8712-90a83df19306

package/dist/sdk/files.d.ts

@@ -1,6 +1,7 @@
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { ItemDocument, LinkedFile, LinkScope } from "../types/index.js";
 import { type LinkedPathValidation } from "./linked-artifacts.js";
+import { type SourceLineRange, type SourceTraceabilityExplanation, type SourceTraceabilityReceipt } from "./traceability/source-traceability.js";
 /** Documents the files command options payload exchanged by command, SDK, and package integrations. */
 export interface FilesCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -112,6 +113,12 @@ export interface FilesLookupOptions {
     noTruncate?: boolean;
     /** Fail when any authoritative item cannot be read. */
     strictRead?: boolean;
+    /** Include rationale, governing-decision paths, and ambiguity receipts. */
+    explain?: boolean;
+    /** Optional inclusive line range; implies explain and requires one path. */
+    lineRange?: SourceLineRange;
+    /** Maximum relationship depth searched for a governing decision. */
+    decisionDepth?: number;
 }
 /** Token-efficient item identity returned by reverse linked-file lookup. */
 export interface FilesLookupItem {
@@ -134,6 +141,8 @@ export interface FilesLookupMatch {
     item: FilesLookupItem;
     /** Matching linked-file evidence. */
     files: LinkedFile[];
+    /** Optional bounded rationale and line-attribution explanation. */
+    traceability?: SourceTraceabilityExplanation;
 }
 /** Reverse linked-file lookup result with bounded output and read provenance. */
 export interface FilesLookupResult {
@@ -160,6 +169,8 @@ export interface FilesLookupResult {
     warnings: string[];
     /** Ordered reverse-traceability matches. */
     matches: FilesLookupMatch[];
+    /** Aggregate receipt for an explained source query. */
+    traceability_receipt?: SourceTraceabilityReceipt;
 }
 interface TextReference {
     field: string;

package/dist/sdk/files.js

@@ -4,7 +4,7 @@
  * Implements the pm files 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]="5e45d0f1-a1a7-50ea-a9a3-ec6283d3471d")}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]="515cd35c-8e0e-51d4-8ad9-1cea5be8a572")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../core/fs/fs-utils.js";
@@ -20,6 +20,7 @@ import { readSettings } from "../core/store/settings.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { isPathWithinDirectory } from "../core/fs/path-utils.js";
 import { dedupeLinkedArtifacts, normalizeLinkedPath, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, } from "./linked-artifacts.js";
+import { explainSourceTraceability, } from "./traceability/source-traceability.js";
 /** Bounds fuzzy relative-path scanning while preserving full absolute-path discovery. */
 const RELATIVE_REFERENCE_SCAN_MAX_CHARS = 32_768;
 function normalizeCandidatePathForOutput(value) {
@@ -251,8 +252,51 @@ function projectFilesLookupItem(item) {
         updated_at: item.updated_at,
     };
 }
+function compareFilesLookupCandidates(left, right) {
+    const byPriority = left.item.priority - right.item.priority;
+    if (byPriority !== 0)
+        return byPriority;
+    const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
+    return byUpdated === 0
+        ? left.item.id.localeCompare(right.item.id)
+        : byUpdated;
+}
+function matchingFilesLookupCandidates(params) {
+    return params.metadata
+        .map((item) => ({
+        item,
+        files: (item.files ?? [])
+            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
+            (params.scope === undefined || file.scope === params.scope))
+            .sort((left, right) => {
+            const byPath = left.path.localeCompare(right.path);
+            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
+        }),
+    }))
+        .filter((match) => match.files.length > 0)
+        .sort(compareFilesLookupCandidates);
+}
+async function resolveFilesLookupTraceability(params) {
+    if (!params.explain)
+        return undefined;
+    return explainSourceTraceability({
+        workspaceRoot: params.workspaceRoot,
+        paths: params.paths,
+        candidates: params.matching,
+        corpus: params.metadata,
+        ...(params.lineRange ? { lineRange: params.lineRange } : {}),
+        ...(params.decisionDepth === undefined
+            ? {}
+            : { decisionDepth: params.decisionDepth }),
+    });
+}
 async function queryFilesLookupIndex(params) {
-    if ([params.strictRead, params.noTruncate, hasActiveOnReadHooks()].includes(true)) {
+    if ([
+        params.strictRead,
+        params.noTruncate,
+        params.explain,
+        hasActiveOnReadHooks(),
+    ].includes(true)) {
         return null;
     }
     const indexState = await readItemMetadataDerivedIndexState(params.pmRoot, [
@@ -272,32 +316,34 @@ async function queryFilesLookupIndex(params) {
 async function queryFilesLookupSource(params) {
     const warnings = [];
     const metadata = await listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, warnings, params.settings.schema);
-    const matching = metadata
-        .map((item) => ({
-        item,
-        files: (item.files ?? [])
-            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
-            (params.scope === undefined || file.scope === params.scope))
-            .sort((left, right) => {
-            const byPath = left.path.localeCompare(right.path);
-            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
-        }),
-    }))
-        .filter((match) => match.files.length > 0)
-        .sort((left, right) => {
-        const byPriority = left.item.priority - right.item.priority;
-        if (byPriority !== 0)
-            return byPriority;
-        const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
-        return byUpdated === 0
-            ? left.item.id.localeCompare(right.item.id)
-            : byUpdated;
+    const matching = matchingFilesLookupCandidates({
+        metadata,
+        paths: params.paths,
+        scope: params.scope,
     });
     const readWarnings = warnings.filter((warning) => /^item_list_(?:item|directory)_read_failed:/u.test(warning));
     if (params.strictRead && readWarnings.length > 0) {
         throw new PmCliError(`Files lookup could not read every item: ${readWarnings.join("; ")}`, EXIT_CODE.GENERIC_FAILURE);
     }
-    const page = matching.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
+    const traceability = await resolveFilesLookupTraceability({
+        explain: params.explain,
+        workspaceRoot: params.workspaceRoot,
+        paths: params.paths,
+        matching,
+        metadata,
+        lineRange: params.lineRange,
+        decisionDepth: params.decisionDepth,
+    });
+    const ranked = traceability
+        ? [...matching].sort((left, right) => {
+            const byScore = traceability.explanations.get(right.item.id).score -
+                traceability.explanations.get(left.item.id).score;
+            if (byScore !== 0)
+                return byScore;
+            return compareFilesLookupCandidates(left, right);
+        })
+        : matching;
+    const page = ranked.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
     return {
         paths: params.paths,
         total: matching.length,
@@ -314,7 +360,11 @@ async function queryFilesLookupSource(params) {
         matches: page.map((match) => ({
             item: projectFilesLookupItem(match.item),
             files: match.files,
+            ...(traceability
+                ? { traceability: traceability.explanations.get(match.item.id) }
+                : {}),
         })),
+        ...(traceability ? { traceability_receipt: traceability.receipt } : {}),
     };
 }
 /** Resolve the pm items that reference one or more source paths. */
@@ -325,6 +375,9 @@ export async function runFilesLookup(options, global) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const paths = await normalizeFilesLookupPaths(options.paths, workspaceRoot);
+    if (options.lineRange && paths.length !== 1) {
+        throw new PmCliError("Files lookup line attribution requires exactly one source path.", EXIT_CODE.USAGE);
+    }
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const { offset, limit } = resolveFilesLookupWindow(options);
@@ -337,6 +390,7 @@ export async function runFilesLookup(options, global) {
         offset,
         strictRead: options.strictRead === true,
         noTruncate: options.noTruncate === true,
+        explain: options.explain === true || options.lineRange !== undefined,
     });
     if (indexed) {
         return {
@@ -364,6 +418,10 @@ export async function runFilesLookup(options, global) {
         limit,
         offset,
         strictRead: options.strictRead === true,
+        workspaceRoot,
+        explain: options.explain === true || options.lineRange !== undefined,
+        lineRange: options.lineRange,
+        decisionDepth: options.decisionDepth,
     });
 }
 /** Implements run files discover for the public runtime surface of this module. */
@@ -479,4 +537,4 @@ export async function runFilesDiscover(id, options, global) {
     };
 }
 //# sourceMappingURL=files.js.map
-//# debugId=5e45d0f1-a1a7-50ea-a9a3-ec6283d3471d
+//# debugId=515cd35c-8e0e-51d4-8ad9-1cea5be8a572

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

@@ -4,7 +4,7 @@
  * Generated by scripts/generate-error-code-catalog.mjs. Do not edit manually.
  */
 
-!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]="94952ea0-bfe7-5d64-9ac4-101c483b4c55")}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]="07d93565-d5ef-5c3d-ae8a-214973e6ec20")}catch(e){}}();
 import { definePmErrorCodeCatalog } from "./error-code-catalog.js";
 /** Exhaustive catalog generated from literal error guidance declarations. */
 export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
@@ -116,6 +116,18 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         canonical_code: "append_empty_body",
         aliases: [],
     },
+    {
+        code: "assurance_registry_invalid",
+        meaning: "Assurance registry invalid condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/governance/assurance.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "assurance_registry_invalid",
+        aliases: [],
+    },
     {
         code: "body_file_conflicts_with_body",
         meaning: "Body file conflicts with body condition.",
@@ -2246,13 +2258,16 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         code: "tracker_not_initialized",
         meaning: "Tracker not initialized condition.",
         stability: "stable",
-        exit_code: 1,
-        class: "generic_failure",
+        exit_code: 3,
+        class: "not_found",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
         sources: ["cli/error-guidance.ts", "core/telemetry/observability.ts"],
         emitting_commands: ["*"],
         canonical_code: "tracker_not_initialized",
         aliases: [],
+        owned_states: [
+            { state: "selected_tracker_root_is_a_regular_file", probe_id: "tracker-root-regular-file", entrypoints: ["list"], expected_exit_class: "not_found" },
+        ],
     },
     {
         code: "tracker_root_missing",
@@ -2385,9 +2400,9 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         exit_code: 2,
         class: "usage",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/extension.ts"],
+        sources: ["sdk/agent/subcommand-recovery.ts"],
         emitting_commands: ["*"],
-        canonical_code: "unknown_lifecycle_action",
+        canonical_code: "unknown_subcommand",
         aliases: [],
     },
     {
@@ -2401,6 +2416,9 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         emitting_commands: ["*"],
         canonical_code: "unknown_option",
         aliases: [],
+        owned_states: [
+            { state: "declared_option_is_rejected_on_the_selected_command_path", probe_id: "cross-command-unknown-option", entrypoints: ["deps"], expected_exit_class: "usage" },
+        ],
     },
     {
         code: "unknown_plan_template",
@@ -2445,15 +2463,16 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
         exit_code: 2,
         class: "usage",
         recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: [
-            "cli/register-mutation.ts",
-            "cli/register-operations.ts",
-            "sdk/runtime-extended-actions.ts",
-            "sdk/telemetry.ts",
-        ],
+        sources: ["cli/error-guidance.ts", "sdk/agent/subcommand-recovery.ts"],
         emitting_commands: ["*"],
         canonical_code: "unknown_subcommand",
-        aliases: [],
+        aliases: ["unknown_lifecycle_action"],
+        owned_states: [
+            { state: "config_action_token_is_not_declared", probe_id: "config-unknown-action", entrypoints: ["config"], expected_exit_class: "usage" },
+            { state: "graph_command_token_is_not_declared", probe_id: "graph-unknown-subcommand", entrypoints: ["graph"], expected_exit_class: "usage" },
+            { state: "nested_command_token_is_not_declared_by_its_family", probe_id: "schema-unknown-subcommand", entrypoints: ["schema"], expected_exit_class: "usage" },
+            { state: "package_lifecycle_token_is_not_declared", probe_id: "package-unknown-action", entrypoints: ["package"], expected_exit_class: "usage" },
+        ],
     },
     {
         code: "unsupported_update_option",
@@ -3129,4 +3148,4 @@ export const PM_ERROR_CODE_CATALOG = definePmErrorCodeCatalog([
     },
 ]);
 //# sourceMappingURL=generated-error-code-catalog.js.map
-//# debugId=94952ea0-bfe7-5d64-9ac4-101c483b4c55
+//# debugId=07d93565-d5ef-5c3d-ae8a-214973e6ec20