@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/stats.js

@@ -4,7 +4,7 @@
  * Implements the pm stats 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]="a4de53c1-bb22-591f-a064-142c642a2443")}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]="d28c7ac7-9801-5b0c-84c9-51deede398be")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -36,6 +36,53 @@ function zeroByStatus(statuses) {
         return acc;
     }, {});
 }
+function projectStatsDistributions(items, itemTypes, statuses, classifier, includeEmpty) {
+    const grouped = groupItemsByDimension(items, "type", classifier);
+    const presentTypes = new Set(grouped.rows.map((row) => row.key));
+    const missingTypes = itemTypes.filter((type) => !presentTypes.has(type));
+    const groupedRows = includeEmpty
+        ? [
+            ...grouped.rows,
+            ...missingTypes.map((type) => ({
+                label: type,
+                key: type,
+                total: 0,
+                buckets: {
+                    open: 0,
+                    in_progress: 0,
+                    blocked: 0,
+                    draft: 0,
+                    closed: 0,
+                    canceled: 0,
+                    other: 0,
+                },
+            })),
+        ]
+        : grouped.rows;
+    const byType = groupedRows.map((row) => ({
+        type: row.key ?? row.label,
+        total: row.total,
+        open: row.buckets.open,
+        in_progress: row.buckets.in_progress,
+        blocked: row.buckets.blocked,
+        draft: row.buckets.draft,
+        closed: row.buckets.closed,
+        canceled: row.buckets.canceled,
+        other: row.buckets.other,
+    }));
+    const counts = zeroByStatus([...statuses]);
+    for (const item of items)
+        counts[item.status] += 1;
+    const byStatus = Object.fromEntries(Object.entries(counts).filter(([, count]) => includeEmpty || count > 0));
+    return {
+        byType,
+        byStatus,
+        omitted: includeEmpty
+            ? 0
+            : missingTypes.length +
+                Object.values(counts).filter((count) => count === 0).length,
+    };
+}
 function countNonEmptyLines(raw) {
     if (raw.trim().length === 0) {
         return 0;
@@ -75,6 +122,7 @@ export const _testOnly = {
     zeroByStatus,
     countNonEmptyLines,
     readHistoryStreamContents,
+    projectStatsDistributions,
 };
 async function recordStatsObservations(global, options) {
     const recorded = [];
@@ -129,12 +177,13 @@ async function requestedHistoryAnalytics(pmRoot, items, settings, terminalStatus
             : undefined,
     };
 }
-function assembleStatsResult(totals, byType, byStatus, optional) {
+function assembleStatsResult(totals, byType, byStatus, omittedZeroBuckets, optional) {
     const hasBreakdowns = Object.keys(optional.breakdowns).length > 0;
     return {
         totals,
         by_type: byType,
         by_status: byStatus,
+        omitted_zero_buckets: omittedZeroBuckets,
         ...(optional.metadataCoverage
             ? { metadata_coverage: optional.metadataCoverage }
             : {}),
@@ -180,16 +229,8 @@ export async function runStats(global, options = {}) {
         itemIds: items.map((item) => item.id),
         commandLabel: "stats",
     });
-    const byType = zeroByType(typeRegistry.types);
-    const byStatus = zeroByStatus(statusRegistry.definitions.map((definition) => definition.id));
-    // zeroByType/zeroByStatus pre-seed a bucket for every registry type/status, and
-    // the light item-metadata reader drops any item whose type/status falls outside
-    // the active registry (parse rejects them) — so every item's bucket is already
-    // present here and no on-the-fly initialization is reachable.
-    for (const item of items) {
-        byType[item.type] += 1;
-        byStatus[item.status] += 1;
-    }
+    const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
+    const distributions = projectStatsDistributions(items, typeRegistry.types, statusRegistry.definitions.map((definition) => definition.id), classifier, options.includeEmpty === true);
     const streams = await readHistoryStreamContents(pmRoot);
     let historyEntries = 0;
     for (const stream of streams) {
@@ -198,7 +239,6 @@ export async function runStats(global, options = {}) {
     const storage = options.storage
         ? computeHistoryStorageStats(streams)
         : undefined;
-    const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
     const metadataCoverage = options.metadataCoverage
         ? computeMetadataCoverage(items, classifier)
         : undefined;
@@ -219,7 +259,7 @@ export async function runStats(global, options = {}) {
         items: items.length,
         history_streams: streams.length,
         history_entries: historyEntries,
-    }, byType, byStatus, {
+    }, distributions.byType, distributions.byStatus, distributions.omitted, {
         metadataCoverage,
         breakdowns,
         storage,
@@ -231,4 +271,4 @@ export async function runStats(global, options = {}) {
     });
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=a4de53c1-bb22-591f-a064-142c642a2443
+//# debugId=d28c7ac7-9801-5b0c-84c9-51deede398be

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/test/execution.d.ts

@@ -35,6 +35,8 @@ export interface TestCommandOptions {
     addJson?: string[];
     /** Value that configures or reports remove for this contract. */
     remove?: string[];
+    /** Remove linked tests by their stable 1-based list position. */
+    removeIndex?: Array<string | number>;
     /** Value that configures or reports list for this contract. */
     list?: boolean;
     /** Value that configures or reports run for this contract. */
@@ -146,6 +148,8 @@ export interface TestResult {
     changed: boolean;
     /** Value that configures or reports count for this contract. */
     count: number;
+    /** Number of linked-test entries removed by this mutation. */
+    removed?: number;
     /** Measurements supplied for the current producing run. */
     measurements?: TestRunMeasurement[];
     /** Existing and current measurements below the selected threshold. */

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test 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]="2c0646bf-44d7-521f-aea1-b0683d88a8fa")}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]="b40f54be-2d3e-5b98-9d49-cb8608a782f5")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -507,7 +507,6 @@ function parseAddJsonEntries(raw) {
         return parsed;
     });
 }
-/* c8 ignore stop */
 function parseRemoveEntries(raw) {
     if (!raw)
         return [];
@@ -516,19 +515,48 @@ function parseRemoveEntries(raw) {
         if (!trimmed) {
             throw new PmCliError("--remove requires command or path value", EXIT_CODE.USAGE);
         }
-        if (trimmed.includes("=") ||
-            /^(?:[-*+]\s+)?(?:path|command)\s*[:=]/i.test(trimmed) ||
+        const identityPrefix = /^(command|path)\s*=/i.exec(trimmed);
+        if (identityPrefix) {
+            const value = trimmed.slice(identityPrefix[0].length).trim();
+            if (!value) {
+                throw new PmCliError("--remove requires a non-empty command=<value> or path=<value>", EXIT_CODE.USAGE);
+            }
+            return {
+                kind: identityPrefix[1].toLowerCase(),
+                value,
+            };
+        }
+        if (/^[A-Za-z_][\w-]*=\S+$/u.test(trimmed)) {
+            throw new PmCliError("--remove structured selectors require command=<value> or path=<value>", EXIT_CODE.USAGE);
+        }
+        if (/^(?:[-*+]\s+)?(?:path|command)\s*:/i.test(trimmed) ||
             trimmed.startsWith("```")) {
             const kv = parseCsvKv(trimmed, "--remove");
+            const kind = kv.path !== undefined ? "path" : "command";
             const value = kv.path ?? kv.command;
             if (!value?.trim()) {
                 throw new PmCliError("--remove requires command=<value> and/or path=<value>", EXIT_CODE.USAGE);
             }
-            return value.trim();
+            return { kind, value: value.trim() };
         }
-        return trimmed;
+        return { kind: "either", value: trimmed };
     });
 }
+function parseRemoveIndexes(raw) {
+    if (!raw)
+        return [];
+    return [
+        ...new Set(raw.map((value) => {
+            const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+            if (!Number.isInteger(parsed) ||
+                parsed < 1 ||
+                String(parsed) !== String(value).trim()) {
+                throw new PmCliError("--remove-index must be a positive integer", EXIT_CODE.USAGE);
+            }
+            return parsed;
+        })),
+    ];
+}
 function closeLinkedTestStdin(child) {
     // Force EOF on child stdin so non-interactive runs do not wait on input.
     try {
@@ -1383,7 +1411,10 @@ function resolveLinkedTestPreflightResult(params) {
 }
 function buildLinkedTestExecutionEnv(params) {
     const effectiveDirectives = resolveEffectiveLinkedTestDirectives(params.runtimeDirectives, params.linkedTest);
-    const executionEnv = { ...process.env };
+    const executionEnv = {
+        ...process.env,
+        SENTRY_ENVIRONMENT: "test",
+    };
     applyEnvDirectiveStage(executionEnv, params.runtimeDirectives);
     applyEnvDirectiveStage(executionEnv, {
         env_set: params.linkedTest.env_set ?? {},
@@ -1538,6 +1569,7 @@ async function readLinkedTestItem(params) {
         tests: loaded.document.metadata.tests ?? [],
         testRuns: loaded.document.metadata.test_runs ?? [],
         changed: false,
+        removed: 0,
     };
 }
 function linkedTestsHaveSameIdentity(left, right) {
@@ -1555,15 +1587,26 @@ function appendMissingLinkedTests(current, additions) {
     }
     return next;
 }
-function removeLinkedTestsBySelector(current, removals) {
-    if (removals.length === 0) {
-        return current;
+function removeLinkedTestsBySelector(current, removals, removeIndexes) {
+    if (removals.length === 0 && removeIndexes.length === 0) {
+        return { tests: current, removed: 0 };
     }
-    return current.filter((entry) => !removals.includes(entry.path ?? "") &&
-        !removals.includes(entry.command ?? ""));
+    const indexSet = new Set(removeIndexes);
+    const tests = current.filter((entry, index) => {
+        if (indexSet.has(index + 1))
+            return false;
+        return !removals.some((selector) => {
+            if (selector.kind === "command")
+                return entry.command === selector.value;
+            if (selector.kind === "path")
+                return entry.path === selector.value;
+            return entry.command === selector.value || entry.path === selector.value;
+        });
+    });
+    return { tests, removed: current.length - tests.length };
 }
-function applyLinkedTestMutations(previous, adds, removes) {
-    return removeLinkedTestsBySelector(appendMissingLinkedTests(previous, adds), removes);
+function applyLinkedTestMutations(previous, adds, removes, removeIndexes) {
+    return removeLinkedTestsBySelector(appendMissingLinkedTests(previous, adds), removes, removeIndexes);
 }
 function hasTestRuntimeDirectiveFlags(options) {
     return ((options.envSet?.length ?? 0) > 0 ||
@@ -1590,25 +1633,43 @@ function assertTestRunFlagUsage(options) {
     }
 }
 async function resolveLinkedTestItem(params) {
-    const { id, options, pmRoot, settings, typeToFolder, adds, removes } = params;
-    if (adds.length === 0 && removes.length === 0) {
+    const { id, options, pmRoot, settings, typeToFolder, adds, removes, removeIndexes, } = params;
+    if (adds.length === 0 && removes.length === 0 && removeIndexes.length === 0) {
         return readLinkedTestItem({ id, pmRoot, settings, typeToFolder });
     }
+    let removed = 0;
     const result = await mutateItem({
         pmRoot,
         settings,
         id,
-        op: "tests_add",
+        op: adds.length > 0 ? "tests_add" : "tests_remove",
         author: resolveAuthor(options.author, settings.author_default),
         message: options.message,
         force: options.force,
         skipNoop: true,
         mutate(document) {
             const previous = document.metadata.tests ?? [];
-            const next = applyLinkedTestMutations(previous, adds, removes);
-            document.metadata.tests = next;
+            const mutation = applyLinkedTestMutations(previous, adds, removes, removeIndexes);
+            removed = mutation.removed;
+            if ((removes.length > 0 || removeIndexes.length > 0) && removed === 0) {
+                throw new PmCliError("No linked tests matched the requested removal selector", EXIT_CODE.NOT_FOUND, {
+                    code: "linked_test_remove_no_match",
+                    unmatched: [
+                        ...removes.map((entry) => `${entry.kind}=${entry.value}`),
+                        ...removeIndexes.map((index) => `index=${index}`),
+                    ],
+                    required: "List linked tests and retry with an exact command/path or a current 1-based --remove-index.",
+                    examples: [
+                        `pm test ${id} --list`,
+                        `pm test ${id} --remove-index 1`,
+                    ],
+                });
+            }
+            document.metadata.tests = mutation.tests;
             return {
-                changedFields: stableValueEquals(previous, next) ? [] : ["tests"],
+                changedFields: stableValueEquals(previous, mutation.tests)
+                    ? []
+                    : ["tests"],
             };
         },
     });
@@ -1617,6 +1678,7 @@ async function resolveLinkedTestItem(params) {
         tests: result.item.tests ?? [],
         testRuns: result.item.test_runs ?? [],
         changed: result.changedFields.length > 0,
+        removed,
     };
 }
 function resolveTestRunOptions(options, tests) {
@@ -1780,6 +1842,7 @@ export async function runTest(id, options, global) {
         ...parseAddJsonEntries(resolvedAddJsons),
     ];
     const removes = parseRemoveEntries(resolvedRemoves);
+    const removeIndexes = parseRemoveIndexes(options.removeIndex);
     const item = await resolveLinkedTestItem({
         id,
         options,
@@ -1788,6 +1851,7 @@ export async function runTest(id, options, global) {
         typeToFolder: typeRegistry.type_to_folder,
         adds,
         removes,
+        removeIndexes,
     });
     const runOptions = resolveTestRunOptions(options, item.tests);
     const runStartedAt = options.run === true ? nowIso() : undefined;
@@ -1835,6 +1899,7 @@ export async function runTest(id, options, global) {
         warnings: warnings.length > 0 ? warnings : undefined,
         changed: item.changed,
         count: item.tests.length,
+        ...(item.removed > 0 ? { removed: item.removed } : {}),
         ...measurementProjection,
     };
 }
@@ -1874,4 +1939,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=2c0646bf-44d7-521f-aea1-b0683d88a8fa
+//# debugId=b40f54be-2d3e-5b98-9d49-cb8608a782f5

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 {};