@unbrained/pm-cli 2026.8.10 → 2026.8.11

package/dist/sdk/runtime.d.ts

@@ -15,6 +15,8 @@ export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./re
 export type { PmContextIntentContract } from "./context-intent-contracts.js";
 export type { PmErrorCodeContract } from "./error-code-catalog.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
+import { type AssuranceActionInput, type AssuranceActionResult } from "./governance/assurance-action.js";
+export type * from "./governance/assurance-action-contracts.js";
 import { type AggregateOptions, type AggregateResult } from "./query/aggregate.js";
 import { type UpgradeCommandOptions, type UpgradeResult } from "./governance/upgrade.js";
 import { type CreateResult } from "./lifecycle/create.js";
@@ -235,6 +237,8 @@ export declare class PmClient {
     health<Options extends ReadOptions<RunHealthOptions> = RunHealthOptions>(options?: Options): ReadPromise<HealthResult, Options>;
     /** Run tracker cache/runtime garbage collection. */
     gc(options?: GcCommandOptions): Promise<GcResult>;
+    /** Declare, inspect, or evaluate a project assurance contract. */
+    assurance(input: AssuranceActionInput): Promise<AssuranceActionResult>;
     /** Redact sensitive values while preserving an audited, verified history chain. */
     historyRedact(id: string, options: HistoryRedactCommandOptions): Promise<HistoryRedactResult>;
     /** Repair and re-anchor one drifted history stream. */

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="70ce3cab-35f0-508b-9348-2f8479495946")}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]="a294f940-5bb9-55a4-bf2c-64842a3a177b")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -28,11 +28,13 @@ import { PM_TOOL_ACTIONS } from "./cli-contracts/enum-contracts.js";
 import { clearWorkspaceContractsCache, memoizeWorkspaceExtensionRegistrations, } from "./workspace-contracts-cache.js";
 import { SDK_ACTION_ALIASES } from "./runtime-action-aliases.js";
 import { createExtensionCommandSdk } from "./extension-command-context.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { applyContextIntentProjection, attachReadOutputContracts, } from "./context-intent-contracts.js";
 import { runWithDiscoveredContextIntentContracts, } from "./context-intent-runtime.js";
 import { validateReadOutputOptions, } from "./read-output-contracts.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
 import { runActivity } from "./query/activity.js";
+import { runAssuranceDispatch } from "./governance/assurance-action.js";
 import { runAggregate, } from "./query/aggregate.js";
 import { runAppend } from "./lifecycle/append.js";
 import { runClaim, runClaimNext, runRelease } from "./lifecycle/claim.js";
@@ -63,7 +65,7 @@ import { runConfig } from "./config.js";
 import { runInit } from "./init.js";
 import { runRuntimeEvalAction, runRuntimeEventsAction, runRuntimeMergeAction, runRuntimeSchedulingAction, runRuntimeWorkspaceAction, } from "./runtime-extended-actions.js";
 import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-attribution.js";
-import { runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
+import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
 import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
@@ -71,6 +73,7 @@ import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
 import { runGraph, } from "./graph/run.js";
 import { runFiles, runFilesDiscover, runFilesLookup } from "./files.js";
+import { runtimeFilesLookupOptions } from "./traceability/runtime-files-lookup.js";
 import { runContracts, } from "./cli-contracts/runtime-contracts.js";
 import { runList } from "./query/list.js";
 import { runSearch, } from "./query/search.js";
@@ -81,7 +84,7 @@ import { runTelemetry } from "./telemetry.js";
 import { runTest } from "./test/execution.js";
 import { runTestAll } from "./test/batch.js";
 import { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-import { runSchemaAddField, runSchemaAddStatus, runSchemaAddType, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaEvolutionMigration, runSchemaRemoveField, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowField, runSchemaShowStatus, } from "./schema.js";
+import { SCHEMA_SUBCOMMANDS, runSchemaAddField, runSchemaAddStatus, runSchemaAddType, runSchemaApplyPreset, runSchemaInferTypes, runSchemaList, runSchemaListFields, runSchemaEvolutionMigration, runSchemaRemoveField, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowField, runSchemaShowStatus, } from "./schema.js";
 export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 export { appendHistoryEntry, createHistoryEntry, } from "../core/history/history.js";
@@ -408,6 +411,10 @@ export class PmClient {
     gc(options = {}) {
         return this.runTyped("gc", { options });
     }
+    /** Declare, inspect, or evaluate a project assurance contract. */
+    assurance(input) {
+        return this.runTyped("assurance", { options: { ...input, subcommand: input.action } });
+    }
     /** Redact sensitive values while preserving an audited, verified history chain. */
     historyRedact(id, options) {
         return this.runTyped("history-redact", { id, options });
@@ -1401,25 +1408,20 @@ function runMcpCommentsAction(ctx) {
         commentOptions.delete === undefined;
     if (isListing) {
         commentOptions.includeMeta = true;
-        if (commentOptions.limit === undefined && commentOptions.fullHistory !== true) {
+        if (commentOptions.limit === undefined &&
+            commentOptions.fullHistory !== true) {
             commentOptions.limit = "20";
         }
     }
     return runComments(requireMcpItemId(ctx), commentOptions, ctx.global);
 }
+function runMcpFilesLookupAction(ctx, paths) {
+    return runFilesLookup(runtimeFilesLookupOptions(ctx.options, paths, parseMcpInteger), ctx.global);
+}
 function runMcpFilesAction(ctx) {
     const lookupPaths = readStringArray(ctx.options.lookupPath);
     if (lookupPaths && lookupPaths.length > 0) {
-        return runFilesLookup({
-            paths: lookupPaths,
-            scope: ctx.options.scope === "project" || ctx.options.scope === "global"
-                ? ctx.options.scope
-                : undefined,
-            limit: parseMcpInteger(ctx.options.limit, "files lookup limit"),
-            offset: parseMcpInteger(ctx.options.offset, "files lookup offset"),
-            noTruncate: ctx.options.noTruncate === true,
-            strictRead: ctx.options.strictRead === true,
-        }, ctx.global);
+        return runMcpFilesLookupAction(ctx, lookupPaths);
     }
     const fileId = requireMcpItemId(ctx);
     return ctx.options.discover === true
@@ -1644,7 +1646,12 @@ function runMcpSchemaAction(ctx) {
         }
         return runMcpSchemaAddTypeAction(schema);
     }
-    throw new PmCliError(`Unknown pm schema subcommand "${schema.subcommand}". Allowed: add-type, remove-type, add-status, remove-status, add-field, remove-field, rename-type, rename-field, remap-status, list-fields, show-field, apply-preset, list, show, show-status`, 64);
+    throw createUnknownSubcommandError({
+        command_path: "schema",
+        token: schema.subcommand,
+        allowed: SCHEMA_SUBCOMMANDS,
+        exit_code: 64,
+    });
 }
 function runMcpProfileAction(ctx) {
     const subcommand = readString(ctx.args, "subcommand") ??
@@ -1663,7 +1670,12 @@ function runMcpProfileAction(ctx) {
     };
     const handler = getOwnHandler(handlers, normalizedSubcommand);
     if (!handler) {
-        throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: list, show, apply, lint`, 64);
+        throw createUnknownSubcommandError({
+            command_path: "profile",
+            token: subcommand,
+            allowed: PROFILE_SUBCOMMANDS,
+            exit_code: 64,
+        });
     }
     return handler();
 }
@@ -1813,6 +1825,7 @@ const SDK_ACTION_HANDLERS = {
         runUpdate: (id, options, global) => runUpdate(id, options, global),
     }),
     health: runMcpHealthAction,
+    assurance: (ctx) => runAssuranceDispatch(ctx.args, ctx.options, ctx.global),
     contracts: (ctx) => runContracts(ctx.options, ctx.global),
     config: runMcpConfigAction,
     activity: runMcpActivityAction,
@@ -1825,16 +1838,7 @@ const SDK_ACTION_HANDLERS = {
     deps: (ctx) => runDeps(requireMcpItemId(ctx), ctx.options, ctx.global),
     graph: runMcpGraphAction,
     "files-discover": (ctx) => runFilesDiscover(requireMcpItemId(ctx), ctx.options, ctx.global),
-    "files-lookup": (ctx) => runFilesLookup({
-        paths: readStringArray(ctx.options.paths),
-        scope: ctx.options.scope === "project" || ctx.options.scope === "global"
-            ? ctx.options.scope
-            : undefined,
-        limit: parseMcpInteger(ctx.options.limit, "files lookup limit"),
-        offset: parseMcpInteger(ctx.options.offset, "files lookup offset"),
-        noTruncate: ctx.options.noTruncate === true,
-        strictRead: ctx.options.strictRead === true,
-    }, ctx.global),
+    "files-lookup": (ctx) => runMcpFilesLookupAction(ctx, readStringArray(ctx.options.paths)),
     history: (ctx) => runHistory(requireMcpItemId(ctx), ctx.options, ctx.global),
     "history-redact": (ctx) => runHistoryRedact(requireMcpItemId(ctx), ctx.options, ctx.global),
     "history-repair": runMcpHistoryRepairAction,
@@ -1930,4 +1934,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=70ce3cab-35f0-508b-9348-2f8479495946
+//# debugId=a294f940-5bb9-55a4-bf2c-64842a3a177b

package/dist/sdk/telemetry.js

@@ -4,7 +4,7 @@
  * Implements the pm telemetry 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]="150c6ff7-cfb5-542f-bd3d-3c8088d1086a")}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]="ad3110ca-e85b-5a7e-b0a1-591796c298eb")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
@@ -14,6 +14,7 @@ import { nowIso } from "../core/shared/time.js";
 import { resolveGlobalPmRoot } from "../core/store/paths.js";
 import { readSettings, writeSettings } from "../core/store/settings.js";
 import { flushTelemetryQueueNow } from "../core/telemetry/runtime.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 const TELEMETRY_QUEUE_RELATIVE_PATH = path.join("runtime", "telemetry", "events.jsonl");
 const TELEMETRY_STATE_RELATIVE_PATH = path.join("runtime", "telemetry", "state.json");
 const TELEMETRY_RUNTIME_RELATIVE_PATH = path.join("runtime", "telemetry");
@@ -161,8 +162,10 @@ const normalizeTelemetrySubcommand = (value) => {
     }
     // `value` is always a defined string here: an undefined subcommand normalizes
     // to "status" above (a valid value) and never reaches this throw.
-    throw new PmCliError(`Unknown pm telemetry subcommand "${value}". Allowed: ${TELEMETRY_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, {
-        code: "unknown_subcommand",
+    throw createUnknownSubcommandError({
+        command_path: "telemetry",
+        token: value?.trim() || "<empty>",
+        allowed: TELEMETRY_SUBCOMMANDS,
         examples: [
             "pm telemetry status",
             "pm telemetry flush",
@@ -400,4 +403,4 @@ export async function runTelemetry(options, _global) {
     });
 }
 //# sourceMappingURL=telemetry.js.map
-//# debugId=150c6ff7-cfb5-542f-bd3d-3c8088d1086a
+//# debugId=ad3110ca-e85b-5a7e-b0a1-591796c298eb

package/dist/sdk/traceability/runtime-files-lookup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module sdk/traceability/runtime-files-lookup
+ *
+ * Projects transport-neutral action values into reverse source lookup options.
+ */
+import type { FilesLookupOptions } from "../files.js";
+/** Convert bounded MCP/action values into the public files lookup contract. */
+export declare function runtimeFilesLookupOptions(options: Readonly<Record<string, unknown>>, paths: string[], parseInteger: (value: unknown, label: string) => number | undefined): FilesLookupOptions;

package/dist/sdk/traceability/runtime-files-lookup.js

@@ -0,0 +1,33 @@
+
+!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]="c2ef0de1-bc44-5550-862c-f3929334fbef")}catch(e){}}();
+import { parseSourceLineRange } from "./source-traceability.js";
+/** Convert bounded MCP/action values into the public files lookup contract. */
+export function runtimeFilesLookupOptions(options, paths, parseInteger) {
+    let lineRange;
+    if (typeof options.lines === "string") {
+        lineRange = parseSourceLineRange(options.lines);
+    }
+    else if (options.lineRange !== undefined) {
+        if (options.lineRange === null ||
+            typeof options.lineRange !== "object" ||
+            Array.isArray(options.lineRange)) {
+            throw new RangeError("Source line range must be an object with numeric start and end values.");
+        }
+        lineRange = parseSourceLineRange(`${String(Reflect.get(options.lineRange, "start"))}:${String(Reflect.get(options.lineRange, "end"))}`);
+    }
+    return {
+        paths,
+        scope: options.scope === "project" || options.scope === "global"
+            ? options.scope
+            : undefined,
+        limit: parseInteger(options.limit, "files lookup limit"),
+        offset: parseInteger(options.offset, "files lookup offset"),
+        noTruncate: options.noTruncate === true,
+        strictRead: options.strictRead === true,
+        explain: options.explain === true,
+        lineRange,
+        decisionDepth: parseInteger(options.decisionDepth, "files lookup decision depth"),
+    };
+}
+//# sourceMappingURL=runtime-files-lookup.js.map
+//# debugId=c2ef0de1-bc44-5550-862c-f3929334fbef

package/dist/sdk/traceability/source-traceability.d.ts

@@ -0,0 +1,102 @@
+import type { ItemMetadata, LinkedFile } from "../../types/index.js";
+/** Inclusive one-based source range accepted by traceability lookup. */
+export interface SourceLineRange {
+    /** First included source line. */
+    start: number;
+    /** Last included source line. */
+    end: number;
+}
+/** One evidence class supporting a source-to-item association. */
+export interface SourceTraceabilityEvidence {
+    /** Evidence producer. */
+    kind: "linked_file" | "git_commit";
+    /** Linked path or abbreviated commit identifier. */
+    reference: string;
+    /** Number of selected lines attributed to this evidence. */
+    contribution_lines?: number;
+}
+/** Rationale fields projected without arbitrary body or comment content. */
+export interface SourceTraceabilityRationale {
+    /** User or project value statement. */
+    value: string | null;
+    /** Recorded timing rationale. */
+    why_now: string | null;
+    /** Recorded intended or achieved outcome. */
+    outcome: string | null;
+    /** Recorded implementation objective. */
+    objective: string | null;
+}
+/** Shortest typed path from source-owning work to a governing decision. */
+export interface SourceDecisionPath {
+    /** Whether a unique decision path was found under the bound. */
+    status: "found" | "ambiguous" | "not_found";
+    /** Ordered item identifiers, including source work and decision. */
+    nodes: string[];
+    /** Relationship kinds connecting consecutive nodes. */
+    kinds: string[];
+    /** Equally short governing decision candidates. */
+    alternative_decision_ids: string[];
+}
+/** Explainable fields added to one reverse linked-file match. */
+export interface SourceTraceabilityExplanation {
+    /** Higher values sort first within the original scheduling priority. */
+    score: number;
+    /** Selected source lines attributable to commits naming this item. */
+    contribution_lines: number;
+    /** Structured evidence supporting the association. */
+    evidence: SourceTraceabilityEvidence[];
+    /** Project rationale carried by the item. */
+    rationale: SourceTraceabilityRationale;
+    /** Governing decision path under the declared graph bound. */
+    decision_path: SourceDecisionPath;
+    /** Honest ambiguity codes; an empty list means no ambiguity was observed. */
+    ambiguities: string[];
+}
+/** Aggregate line-attribution receipt returned beside explained matches. */
+export interface SourceTraceabilityReceipt {
+    /** Inclusive selected range, or null for path-only explanation. */
+    line_range: SourceLineRange | null;
+    /** Number of distinct blamed commits. */
+    blamed_commit_count: number;
+    /** Number of blamed commits whose message named at least one pm item. */
+    mapped_commit_count: number;
+    /** Number of blamed commits without an item reference. */
+    unmapped_commit_count: number;
+    /** Maximum relationship depth searched for a governing decision. */
+    decision_depth: number;
+}
+interface TraceabilityCandidate {
+    item: ItemMetadata;
+    files: LinkedFile[];
+}
+interface GitAttribution {
+    commitLines: Map<string, number>;
+    commitItems: Map<string, string[]>;
+    available: boolean;
+}
+/** Parse an inclusive `start:end` source-line selector. */
+export declare function parseSourceLineRange(value: string): SourceLineRange;
+declare function parseBlameCommits(output: string): Map<string, number>;
+declare function parseCommitItemReferences(output: string): Map<string, string[]>;
+declare function shortestDecisionPath(itemId: string, corpus: readonly ItemMetadata[], maxDepth: number): SourceDecisionPath;
+declare function mappedBlamedCommits(attribution: GitAttribution): string[];
+/** Enrich reverse linked-file candidates with bounded source rationale. */
+export declare function explainSourceTraceability(params: {
+    workspaceRoot: string;
+    paths: readonly string[];
+    candidates: readonly TraceabilityCandidate[];
+    corpus: readonly ItemMetadata[];
+    lineRange?: SourceLineRange;
+    decisionDepth?: number;
+}): Promise<{
+    explanations: Map<string, SourceTraceabilityExplanation>;
+    receipt: SourceTraceabilityReceipt;
+}>;
+/** Internal parser and traversal seams for deterministic boundary tests. */
+export declare const _testOnlySourceTraceability: {
+    mappedBlamedCommits: typeof mappedBlamedCommits;
+    parseBlameCommits: typeof parseBlameCommits;
+    parseCommitItemReferences: typeof parseCommitItemReferences;
+    shortestDecisionPath: typeof shortestDecisionPath;
+};
+export {};

package/dist/sdk/traceability/source-traceability.js

@@ -0,0 +1,293 @@
+/**
+ * @module sdk/source-traceability
+ *
+ * Composes linked-file evidence, bounded Git line attribution, item rationale,
+ * and typed relationship paths into an explainable source-to-work projection.
+ */
+
+!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]="b8b3f729-be32-5a77-b08f-f616ee068e0f")}catch(e){}}();
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { assembleWorkspaceRelationshipGraph } from "../graph/assembly.js";
+function runGit(workspaceRoot, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", [...args], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            maxBuffer: 4 * 1024 * 1024,
+        }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+    });
+}
+function validateLineRange(range) {
+    if (range &&
+        (!Number.isSafeInteger(range.start) ||
+            !Number.isSafeInteger(range.end) ||
+            range.start < 1 ||
+            range.end < range.start)) {
+        throw new RangeError("Source line range must be inclusive positive integers with end >= start.");
+    }
+}
+/** Parse an inclusive `start:end` source-line selector. */
+export function parseSourceLineRange(value) {
+    const match = /^(\d+):(\d+)$/u.exec(value.trim());
+    const range = match
+        ? { start: Number(match[1]), end: Number(match[2]) }
+        : undefined;
+    validateLineRange(range);
+    if (!range) {
+        throw new RangeError("Source line range must use start:end.");
+    }
+    return range;
+}
+function parseBlameCommits(output) {
+    const lines = new Map();
+    for (const row of output.split("\n")) {
+        const commit = /^([0-9a-f^]{40,64}) \d+ \d+(?: \d+)?$/u.exec(row)?.[1];
+        if (commit)
+            lines.set(commit, (lines.get(commit) ?? 0) + 1);
+    }
+    return lines;
+}
+function parseCommitItemReferences(output) {
+    const fields = output.split("\0");
+    const references = new Map();
+    for (let index = 0; index + 1 < fields.length; index += 2) {
+        const commit = fields[index]?.trim();
+        if (!commit)
+            continue;
+        const ids = [
+            ...new Set(fields[index + 1]?.match(/\bpm-[a-z0-9][a-z0-9-]{2,63}\b/gu) ?? []),
+        ].sort((left, right) => left.localeCompare(right));
+        references.set(commit, ids);
+    }
+    return references;
+}
+async function readGitAttribution(params) {
+    const relativePath = path.relative(params.workspaceRoot, path.resolve(params.workspaceRoot, params.sourcePath));
+    const blame = await runGit(params.workspaceRoot, [
+        "blame",
+        "--line-porcelain",
+        "-L",
+        `${params.lineRange.start},${params.lineRange.end}`,
+        "--",
+        relativePath,
+    ]);
+    const log = await runGit(params.workspaceRoot, [
+        "log",
+        "-n",
+        "256",
+        "--format=%H%x00%B%x00",
+        "--",
+        relativePath,
+    ]);
+    return {
+        commitLines: parseBlameCommits(blame),
+        commitItems: parseCommitItemReferences(log),
+        available: true,
+    };
+}
+function expandDecisionPath(params) {
+    const tail = params.current.nodes.at(-1);
+    const nextDepth = params.current.kinds.length + 1;
+    let foundDepth;
+    for (const edge of params.graph.incidentEdges(tail)) {
+        const outgoing = edge.source === tail;
+        const next = outgoing ? edge.target : edge.source;
+        if ((params.visitedDepth.get(next) ?? Number.POSITIVE_INFINITY) < nextDepth)
+            continue;
+        params.visitedDepth.set(next, nextDepth);
+        const definition = params.graph.registry().require(edge.kind);
+        const nextPath = {
+            nodes: [...params.current.nodes, next],
+            kinds: [
+                ...params.current.kinds,
+                outgoing ? edge.kind : (definition.inverse ?? edge.kind),
+            ],
+        };
+        if (params.details.get(next)?.type?.toLowerCase() === "decision") {
+            foundDepth = nextDepth;
+            params.found.push(nextPath);
+        }
+        else {
+            params.queue.push(nextPath);
+        }
+    }
+    return foundDepth;
+}
+function collectDecisionPaths(params) {
+    const queue = [
+        { nodes: [params.itemId], kinds: [] },
+    ];
+    const visitedDepth = new Map([[params.itemId, 0]]);
+    const found = [];
+    let foundDepth;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = current.kinds.length;
+        if (foundDepth !== undefined && depth >= foundDepth)
+            continue;
+        if (depth >= params.maxDepth)
+            continue;
+        foundDepth =
+            expandDecisionPath({
+                current,
+                graph: params.graph,
+                details: params.details,
+                visitedDepth,
+                queue,
+                found,
+            }) ?? foundDepth;
+    }
+    found.sort((left, right) => left.nodes.join("\0").localeCompare(right.nodes.join("\0")));
+    return found;
+}
+function shortestDecisionPath(itemId, corpus, maxDepth) {
+    const assembly = assembleWorkspaceRelationshipGraph(corpus);
+    if (!assembly.graph.hasNode(itemId)) {
+        return {
+            status: "not_found",
+            nodes: [],
+            kinds: [],
+            alternative_decision_ids: [],
+        };
+    }
+    const found = collectDecisionPaths({
+        itemId,
+        maxDepth,
+        graph: assembly.graph,
+        details: new Map(assembly.details.map((detail) => [detail.id, detail])),
+    });
+    const selected = found[0];
+    if (!selected) {
+        return {
+            status: "not_found",
+            nodes: [],
+            kinds: [],
+            alternative_decision_ids: [],
+        };
+    }
+    const decisionIds = [...new Set(found.map((entry) => entry.nodes.at(-1)))];
+    return {
+        status: decisionIds.length === 1 ? "found" : "ambiguous",
+        nodes: selected.nodes,
+        kinds: selected.kinds,
+        alternative_decision_ids: decisionIds.slice(1),
+    };
+}
+async function resolveGitAttribution(params) {
+    if (!params.lineRange) {
+        return {
+            commitLines: new Map(),
+            commitItems: new Map(),
+            available: true,
+        };
+    }
+    try {
+        return await readGitAttribution({
+            workspaceRoot: params.workspaceRoot,
+            sourcePath: params.paths[0],
+            lineRange: params.lineRange,
+        });
+    }
+    catch {
+        return {
+            commitLines: new Map(),
+            commitItems: new Map(),
+            available: false,
+        };
+    }
+}
+function sourceAmbiguities(params) {
+    const ambiguities = [];
+    if (params.hasLineRange && !params.attributionAvailable) {
+        ambiguities.push("git_attribution_unavailable");
+    }
+    if (params.hasLineRange && params.contributionLines === 0) {
+        ambiguities.push("line_attribution_unmapped");
+    }
+    if (params.decisionStatus === "ambiguous") {
+        ambiguities.push("multiple_governing_decisions");
+    }
+    if (params.decisionStatus === "not_found") {
+        ambiguities.push("governing_decision_not_found");
+    }
+    return ambiguities;
+}
+function mappedBlamedCommits(attribution) {
+    return [...attribution.commitLines.keys()].filter((commit) => (attribution.commitItems.get(commit)?.length ?? 0) > 0);
+}
+/** Enrich reverse linked-file candidates with bounded source rationale. */
+export async function explainSourceTraceability(params) {
+    validateLineRange(params.lineRange);
+    const decisionDepth = params.decisionDepth ?? 8;
+    if (!Number.isSafeInteger(decisionDepth) ||
+        decisionDepth < 1 ||
+        decisionDepth > 32) {
+        throw new RangeError("Decision path depth must be an integer from 1 to 32.");
+    }
+    const attribution = await resolveGitAttribution(params);
+    const mappedCommits = mappedBlamedCommits(attribution);
+    const explanations = new Map();
+    for (const candidate of params.candidates) {
+        const attributedCommits = [...attribution.commitLines.entries()].filter(([commit]) => attribution.commitItems.get(commit)?.includes(candidate.item.id));
+        const contributionLines = attributedCommits.reduce((total, [, lines]) => total + lines, 0);
+        const decisionPath = shortestDecisionPath(candidate.item.id, params.corpus, decisionDepth);
+        const ambiguities = sourceAmbiguities({
+            hasLineRange: params.lineRange !== undefined,
+            attributionAvailable: attribution.available,
+            contributionLines,
+            decisionStatus: decisionPath.status,
+        });
+        explanations.set(candidate.item.id, {
+            score: contributionLines * 100 +
+                candidate.files.length * 10 +
+                Math.max(0, 9 -
+                    Math.floor((Date.now() - Date.parse(candidate.item.updated_at)) /
+                        (30 * 24 * 60 * 60 * 1000))),
+            contribution_lines: contributionLines,
+            evidence: [
+                ...candidate.files.map((file) => ({
+                    kind: "linked_file",
+                    reference: file.path,
+                })),
+                ...attributedCommits.map(([commit, lines]) => ({
+                    kind: "git_commit",
+                    reference: commit.slice(0, 12),
+                    contribution_lines: lines,
+                })),
+            ],
+            rationale: {
+                value: candidate.item.value?.trim() || null,
+                why_now: candidate.item.why_now?.trim() || null,
+                outcome: candidate.item.outcome?.trim() || null,
+                objective: candidate.item.objective?.trim() || null,
+            },
+            decision_path: decisionPath,
+            ambiguities,
+        });
+    }
+    return {
+        explanations,
+        receipt: {
+            line_range: params.lineRange ?? null,
+            blamed_commit_count: attribution.commitLines.size,
+            mapped_commit_count: mappedCommits.length,
+            unmapped_commit_count: attribution.commitLines.size - mappedCommits.length,
+            decision_depth: decisionDepth,
+        },
+    };
+}
+/** Internal parser and traversal seams for deterministic boundary tests. */
+export const _testOnlySourceTraceability = {
+    mappedBlamedCommits,
+    parseBlameCommits,
+    parseCommitItemReferences,
+    shortestDecisionPath,
+};
+//# sourceMappingURL=source-traceability.js.map
+//# debugId=b8b3f729-be32-5a77-b08f-f616ee068e0f

package/dist/types.d.ts

@@ -743,7 +743,7 @@ export interface HistoryEntry {
     /** Observed agent model identifier, retained in local history. */
     agent_model?: string;
     /** Bounded signal class that supplied `agent_model`. */
-    agent_model_source?: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+    agent_model_source?: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
     /** Privacy-safe fingerprint distinguishing concurrent harness invocations. */
     agent_instance?: string;
     /** Extensible local-only descriptive agent provenance; null means declared but unavailable. */
@@ -751,7 +751,13 @@ export interface HistoryEntry {
         /** Bounded descriptive value observed for this dimension. */
         value: string;
         /** Bounded signal class that supplied the value. */
-        source: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+        source: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
+        /** Confidence attached to a semantic inference. */
+        confidence?: "high" | "medium" | "low";
+        /** Versioned semantic inference rule. */
+        rule_version?: "v2";
+        /** Bounded item and lineage references supporting the inference. */
+        evidence?: readonly string[];
     } | null>>;
     /** Stable declared episode identity; absent on legacy or undeclared events. */
     agent_episode?: {