@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/dist/sdk/provenance.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1f6a4ff8-fc1e-5aac-8117-bae8f325b275")}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]="6162845d-f4b4-5d1f-a210-ddef1a5c38f6")}catch(e){}}();
 import { AGENT_PROVENANCE_DIMENSIONS, BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, } from "../core/shared/author.js";
 /** Resolve the declared or deterministic legacy identity for one history event. */
 export function resolveHistoryEpisodeGroupIdentity(entry) {
@@ -144,6 +144,68 @@ export function summarizeAgentProvenance(entries, dimensions = AGENT_PROVENANCE_
         .sort((left, right) => left.harness.localeCompare(right.harness) ||
         left.dimension.localeCompare(right.dimension));
 }
+/**
+ * Measure role/topic availability by harness and precedence source, then apply
+ * an explicit ratchet. Empty or synthetic corpora therefore remain useful
+ * negative controls instead of silently passing a production coverage gate.
+ */
+export function evaluateSemanticAttributionCoverage(entries, options = {}) {
+    const minimumCoverage = options.minimumCoverage ?? 0.8;
+    const minimumEntries = options.minimumEntries ?? 5;
+    if (![
+        Number.isFinite(minimumCoverage),
+        minimumCoverage >= 0,
+        minimumCoverage <= 1,
+    ].every(Boolean)) {
+        throw new RangeError("Semantic attribution minimum coverage must be from 0 to 1.");
+    }
+    if (![Number.isSafeInteger(minimumEntries), minimumEntries >= 1].every(Boolean)) {
+        throw new RangeError("Semantic attribution minimum entries must be a positive integer.");
+    }
+    const rows = new Map();
+    for (const entry of entries) {
+        if (!entry.agent_harness)
+            continue;
+        for (const dimension of ["role", "topic"]) {
+            const key = `${entry.agent_harness}\0${dimension}`;
+            const row = rows.get(key) ?? {
+                harness: entry.agent_harness,
+                dimension,
+                entries: 0,
+                observed: 0,
+                by_source: {},
+                coverage: 0,
+            };
+            row.entries += 1;
+            const observation = entry.agent_provenance?.[dimension];
+            if (observation?.value) {
+                row.observed += 1;
+                row.by_source[observation.source] =
+                    (row.by_source[observation.source] ?? 0) + 1;
+            }
+            rows.set(key, row);
+        }
+    }
+    const ordered = [...rows.values()]
+        .map((row) => ({
+        ...row,
+        coverage: row.observed / row.entries,
+        by_source: Object.fromEntries(Object.entries(row.by_source).sort(([left], [right]) => left.localeCompare(right))),
+    }))
+        .sort((left, right) => left.harness.localeCompare(right.harness) ||
+        left.dimension.localeCompare(right.dimension));
+    const eligible = ordered.filter((row) => row.entries >= minimumEntries);
+    const failures = eligible
+        .filter((row) => row.coverage < minimumCoverage)
+        .map((row) => `${row.harness}:${row.dimension}`);
+    return {
+        passed: eligible.length > 0 && failures.length === 0,
+        minimum_coverage: minimumCoverage,
+        minimum_entries: minimumEntries,
+        rows: ordered,
+        failures,
+    };
+}
 /**
  * Group immutable history by declared episode keys. Legacy entries fall back
  * to their privacy-safe agent instance, or to a deterministic author cohort.
@@ -194,4 +256,4 @@ export function groupHistoryByEpisode(entries) {
     return roots;
 }
 //# sourceMappingURL=provenance.js.map
-//# debugId=1f6a4ff8-fc1e-5aac-8117-bae8f325b275
+//# debugId=6162845d-f4b4-5d1f-a210-ddef1a5c38f6

package/dist/sdk/query/context.d.ts

@@ -362,6 +362,8 @@ export interface ContextResult {
     focus_fields?: string[];
     /** Value that configures or reports warnings for this contract. */
     warnings?: string[];
+    /** Actionable recovery contracts for context signal-store warnings. */
+    warning_details?: ContextSignalStoreReadResult["warning_details"];
     /** Value that configures or reports ranking for this contract. */
     ranking?: ContextRankingSummary;
     /** Token-budget selection and projection accounting for ranked focus rows. */

package/dist/sdk/query/context.js

@@ -4,7 +4,7 @@
  * Implements the pm context 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]="dbcd4e0e-3fa0-5ce9-8bbc-6de05779d729")}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]="757a0349-9fb6-579d-ab29-fabaad790ce4")}catch(e){}}();
 import { SETTINGS_DEFAULTS, EXIT_CODE, PmCliError, compareTimestampStrings, nowIso, isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, resolveRuntimeStatusRegistry, resolvePmRoot, readSettings, resolveAuthor, discoverExtensions, } from "../runtime-primitives.js";
 import { collectDependencyBlockedIds, resolveItemBlockers, } from "../actionability.js";
 import { CONTEXT_DEPTH_VALUES, CONTEXT_SECTION_VALUES, } from "../../types/index.js";
@@ -20,6 +20,9 @@ import { packContextCandidates, } from "../context-packing.js";
 import { readContextUsageAffinity, recordContextUsageServing, } from "../context-usage.js";
 import { readWorkspaceContextSignals, } from "../context-signal-store.js";
 import { readWorkspaceMemory, selectWorkspaceMemory, } from "../workspace-memory.js";
+import { detectAgentIdentity } from "../../core/shared/author.js";
+import { readSessionState, semanticAttributionKey, } from "../../core/session/session-state.js";
+import { semanticAttributionAffinity } from "../context/semantic-session-attribution.js";
 // ---------------------------------------------------------------------------
 // Output format
 // ---------------------------------------------------------------------------
@@ -1223,7 +1226,7 @@ function resolveContextSubtreeIds(parentScope, fullCorpus) {
     }
     return subtree.ids;
 }
-async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpus, blockedIds, statusRegistry, sectionsIncluded, limit, now, author, cursor, cursorFingerprint, useBoundedPage, pmRoot, tokenBudget) {
+async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpus, blockedIds, statusRegistry, sectionsIncluded, limit, now, author, cursor, cursorFingerprint, useBoundedPage, pmRoot, tokenBudget, claimFocus) {
     const structural = [...listedItemMetadata].sort((left, right) => compareCriticalItems(left, right, statusRegistry));
     const usage = await readContextUsageAffinity({
         pmRoot,
@@ -1237,6 +1240,7 @@ async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpu
         now,
         author,
         usageAffinity: usage.affinity,
+        claimFocus,
     });
     const ranking = await scoreContextCandidatesWithActiveExtensions("context", featureStore.candidates);
     const ranked = ranking.ranked.map((entry) => entry.item);
@@ -1262,7 +1266,9 @@ async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpu
     const packing = packRankedContextItems({
         ...ranking,
         ranked: ranking.ranked.filter((entry) => packingIds.has(entry.id)),
-    }, tokenBudget);
+    }, tokenBudget, new Set(Object.entries(claimFocus ?? {})
+        .filter(([, affinity]) => affinity >= 1)
+        .map(([id]) => id)));
     const packedItems = packing.included.map((entry) => entry.item);
     const activeItems = packedItems.filter((item) => activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)));
     const blockedItems = packedItems.filter((item) => blockedIds.has(item.id.trim().toLowerCase()));
@@ -1297,9 +1303,7 @@ async function resolveContextFocusGroups(listedItemMetadata, allItems, fullCorpu
         highLevel,
         lowLevel,
         blockedFallback: blockedFallbackUsed
-            ? blockedItems
-                .slice(0, limit)
-                .map(projectFocusItem)
+            ? blockedItems.slice(0, limit).map(projectFocusItem)
             : [],
         blockedFallbackUsed,
         ranking,
@@ -1412,7 +1416,7 @@ function buildContextSummaryExtras(needsAllItems, allItems, statusRegistry) {
             canceledStatus).length,
     };
 }
-function attachOptionalContextSections(result, sections) {
+function attachOptionalContextSections(result, sections, warningDetails) {
     if (sections.hierarchy)
         result.hierarchy = sections.hierarchy;
     if (sections.activity)
@@ -1433,6 +1437,9 @@ function attachOptionalContextSections(result, sections) {
         result.staleness = sections.staleness;
     if (sections.tests)
         result.tests = sections.tests;
+    if (warningDetails !== undefined && warningDetails.length > 0) {
+        result.warning_details = warningDetails;
+    }
 }
 function applyContextFocusProjection(result, focusFields) {
     if (!focusFields) {
@@ -1551,6 +1558,12 @@ export async function resolveContextExtensionHealthProjection(omitted, pmRoot, s
         },
     };
 }
+async function resolveContextSemanticAffinity(pmRoot, author) {
+    const identity = detectAgentIdentity();
+    const semanticState = await readSessionState(pmRoot);
+    const attributionKey = identity.instance || semanticAttributionKey(author);
+    return semanticAttributionAffinity(semanticState.semantic_attribution?.[attributionKey]);
+}
 /** Implements run context for the public runtime surface of this module. */
 export async function runContext(options, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
@@ -1563,11 +1576,12 @@ export async function runContext(options, global) {
         tokenBudget: resolveContextTokenBudget(options.tokenBudget, Math.max(256, scaledLimit * 160)),
     };
     const author = resolveAuthor(undefined, runtime.settings.author_default);
+    const claimFocus = await resolveContextSemanticAffinity(pmRoot, author);
     const extensionHealthPromise = resolveContextExtensionHealthProjection(options.noExtensionHealth === true, pmRoot, runtime.settings);
     // Single shared edge-aware blocked classification (GH-578): resolved against
     // the full corpus so terminal blocker targets count as satisfied at every depth.
     const blockedIds = collectDependencyBlockedIds(corpus.fullCorpus, runtime.statusRegistry);
-    const focusGroups = await resolveContextFocusGroups(corpus.listedItemMetadata, corpus.allItems, corpus.fullCorpus, blockedIds, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit, nowIso(), author, options.after, buildContextCursorFingerprint(options), shouldPageContextFocus(options, corpus.fullCorpus.length), pmRoot, runtime.tokenBudget);
+    const focusGroups = await resolveContextFocusGroups(corpus.listedItemMetadata, corpus.allItems, corpus.fullCorpus, blockedIds, runtime.statusRegistry, runtime.sectionsIncluded, runtime.limit, nowIso(), author, options.after, buildContextCursorFingerprint(options), shouldPageContextFocus(options, corpus.fullCorpus.length), pmRoot, runtime.tokenBudget, claimFocus);
     const agendaContext = await buildContextAgenda(global, runtime, corpus.subtreeIds, new Set([
         ...focusGroups.highLevel,
         ...focusGroups.lowLevel,
@@ -1642,7 +1656,7 @@ export async function runContext(options, global) {
     };
     result.workspace_memory = selectWorkspaceMemory(workspaceMemory, Math.min(800, Math.floor(runtime.tokenBudget * 0.2)));
     Object.assign(result, await extensionHealthPromise);
-    attachOptionalContextSections(result, sections);
+    attachOptionalContextSections(result, sections, focusGroups.featureStore.warning_details);
     applyContextTagProjection(result, options.noTags === true);
     if (options.explainRanking === true) {
         result.ranking = toContextRankingSummary(focusGroups.ranking, focusGroups.featureStore);
@@ -1656,4 +1670,4 @@ export async function runContext(options, global) {
     return result;
 }
 //# sourceMappingURL=context.js.map
-//# debugId=dbcd4e0e-3fa0-5ce9-8bbc-6de05779d729
+//# debugId=757a0349-9fb6-579d-ab29-fabaad790ce4

package/dist/sdk/query/light-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { ItemMetadata } from "../../types/index.js";
+/** Read scalar-only metadata using client workspace defaults and custom type folders. */
+export declare function listClientItemMetadataLight(pmRootOverride: string | undefined, cwdOverride: string | undefined): Promise<ItemMetadata[]>;

package/dist/sdk/query/light-metadata.js

@@ -0,0 +1,19 @@
+/**
+ * @module sdk/query/light-metadata
+ *
+ * Resolves workspace settings for the host-bound lightweight metadata reader.
+ */
+
+!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]="6ede8efb-54ec-5b13-a1bf-216b525acc12")}catch(e){}}();
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { listAllItemMetadataLight } from "../../core/store/item-store.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+/** Read scalar-only metadata using client workspace defaults and custom type folders. */
+export async function listClientItemMetadataLight(pmRootOverride, cwdOverride) {
+    const pmRoot = resolvePmRoot(cwdOverride ?? process.cwd(), pmRootOverride);
+    const settings = await readSettings(pmRoot);
+    return listAllItemMetadataLight(pmRoot, settings.item_format, resolveItemTypeRegistry(settings, null).type_to_folder, undefined, settings.schema);
+}
+//# sourceMappingURL=light-metadata.js.map
+//# debugId=6ede8efb-54ec-5b13-a1bf-216b525acc12

package/dist/sdk/runtime-extended-actions.js

@@ -1,7 +1,8 @@
 
-!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]="f8cd69db-ec70-560f-a8c2-2d8d4be75459")}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]="37ac2a74-f150-5b9d-96d6-d9cc441215be")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { runEval } from "./eval.js";
 import { runMergeDriver } from "./merge/driver.js";
@@ -92,14 +93,24 @@ export function runRuntimeMergeAction(context) {
             prefer: readRuntimeString(input, "prefer"),
         }, context.global);
     }
-    throw new PmCliError(`Unknown merge subcommand "${subcommand}".`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+    throw createUnknownSubcommandError({
+        command_path: "merge",
+        token: subcommand,
+        allowed: ["install", "reconcile", "report", "driver"],
+        display_name: "merge",
+    });
 }
 /** Dispatch guarded workspace snapshot operations. */
 export function runRuntimeWorkspaceAction(context) {
     const input = mergedInput(context);
     const subcommand = requiredString(input, "subcommand");
     if (subcommand !== "snapshot") {
-        throw new PmCliError(`Unknown workspace subcommand "${subcommand}".`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        throw createUnknownSubcommandError({
+            command_path: "workspace",
+            token: subcommand,
+            allowed: ["snapshot"],
+            display_name: "workspace",
+        });
     }
     const snapshotAction = readRuntimeString(input, "snapshotAction") ??
         requiredString(input, "snapshot_action");
@@ -129,7 +140,13 @@ export function runRuntimeWorkspaceAction(context) {
                 lockWaitMs: parseRuntimeInteger(input.lockWaitMs, "lockWaitMs"),
             });
     }
-    throw new PmCliError(`Unknown workspace snapshot action "${snapshotAction}".`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+    throw createUnknownSubcommandError({
+        command_path: "workspace snapshot",
+        token: snapshotAction,
+        allowed: ["create", "list", "inspect", "restore", "delete"],
+        display_name: "workspace snapshot",
+        token_kind: "action",
+    });
 }
 /** Dispatch meeting, event, and reminder shortcuts through SDK-owned creation. */
 export function runRuntimeSchedulingAction(context) {
@@ -144,4 +161,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=f8cd69db-ec70-560f-a8c2-2d8d4be75459
+//# debugId=37ac2a74-f150-5b9d-96d6-d9cc441215be

package/dist/sdk/runtime-primitives.d.ts

@@ -8,6 +8,7 @@
  */
 export { type MutationCheckpointItem, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
+export { createUnknownSubcommandError, type UnknownSubcommandErrorOptions, } from "./agent/subcommand-recovery.js";
 export { type ActiveExtensionHookContext, type ExtensionCommandRegistry, type ExtensionDiscoveryResult, type ExtensionHookRegistry, type ExtensionParserRegistry, type ExtensionPreflightRegistry, type ExtensionRegistrationRegistry, type ExtensionRendererRegistry, type ExtensionServiceRegistry, type FlagDefinition, type PreflightRuntimeDecision, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions, type RegisteredExtensionSchemaMigrationDefinition, activateExtensions, clearActiveExtensionHooks, consumeAfterCommandAffectedItems, createCoreCommandHookContext, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, resetActiveExtensionRuntimeState, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, runActiveParserOverride, runActivePreflightOverride, runActiveServiceOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandContext, setActiveCommandResult, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
 export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFieldNames, parseRegisteredItemFieldAssignments, } from "../core/extensions/item-fields.js";
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
@@ -16,6 +17,7 @@ export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } fr
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, createHistoryEntry, hashDocument, hashEmptyDocument, } from "../core/history/history.js";
+export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";

package/dist/sdk/runtime-primitives.js

@@ -7,9 +7,10 @@
  * prefer the typed operations exported by the main 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]="17358714-bb54-58e5-bba0-61bfd1323ec2")}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]="16d4bbae-03b7-5316-8e26-77f33affdcf6")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
+export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
 export { activateExtensions, clearActiveExtensionHooks, consumeAfterCommandAffectedItems, createCoreCommandHookContext, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, resetActiveExtensionRuntimeState, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnIndexHooks, runActiveOnReadHooks, runActiveOnWriteHooks, runActiveParserOverride, runActivePreflightOverride, runActiveServiceOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandContext, setActiveCommandResult, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, } from "../core/extensions/index.js";
 export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFieldNames, parseRegisteredItemFieldAssignments, } from "../core/extensions/item-fields.js";
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
@@ -18,6 +19,7 @@ export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } fr
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, createHistoryEntry, hashDocument, hashEmptyDocument, } from "../core/history/history.js";
+export { readHistoryEntries } from "../core/history/read.js";
 export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
@@ -79,4 +81,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=17358714-bb54-58e5-bba0-61bfd1323ec2
+//# debugId=16d4bbae-03b7-5316-8e26-77f33affdcf6

package/dist/sdk/runtime.d.ts

@@ -7,6 +7,7 @@ export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignore
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export type { FlagDefinition } from "../core/extensions/loader.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
+import type { ItemMetadata } from "../types/index.js";
 export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract, } from "./workspace-contracts.js";
 import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
@@ -14,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";
@@ -74,7 +77,7 @@ export { EXIT_CODE };
 export { PmCliError } from "../core/shared/errors.js";
 export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
 export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore, } from "./similarity-scoring.js";
-export { listAllItemMetadata, locateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { listAllItemMetadata, listAllItemMetadataLight, locateItem, readLocatedItem, } from "../core/store/item-store.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
 export { runAggregate, type AggregateOptions, type AggregateResult, type AggregateRow, } from "./query/aggregate.js";
@@ -131,6 +134,8 @@ export declare class PmClient {
     private runTyped;
     /** Return the same context snapshot produced by `pm context`. */
     context<Options extends ReadOptions<ContextOptions> = ContextOptions>(options?: Options): ReadPromise<ContextResult, Options>;
+    /** Read every item through the scalar-only metadata cache without materializing heavy collections or bodies. */
+    listAllItemMetadataLight(): Promise<ItemMetadata[]>;
     /** List items with the MCP/agent compact defaults. */
     list<Options extends ReadOptions<ListOptions> = ListOptions>(options?: Options): ReadPromise<ListResult, Options>;
     /** Search items with the MCP/agent compact defaults. */
@@ -232,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]="c8f2b88e-1883-5744-868b-3a16f3814813")}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";
@@ -22,16 +22,19 @@ import { createAsyncReadWriteGate } from "../core/shared/serial-queue.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../core/schema/runtime-schema.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
+import { listClientItemMetadataLight } from "./query/light-metadata.js";
 import { buildWorkspaceExtensionCommandContracts, buildWorkspaceFieldContracts, } from "./workspace-contracts.js";
 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";
@@ -62,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";
@@ -70,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";
@@ -80,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";
@@ -99,7 +103,7 @@ export { EXIT_CODE };
 export { PmCliError } from "../core/shared/errors.js";
 export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
 export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, } from "./similarity-scoring.js";
-export { listAllItemMetadata, locateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { listAllItemMetadata, listAllItemMetadataLight, locateItem, readLocatedItem, } from "../core/store/item-store.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
 export { runAggregate, } from "./query/aggregate.js";
@@ -169,6 +173,10 @@ export class PmClient {
     context(options = {}) {
         return this.runTyped("context", { options });
     }
+    /** Read every item through the scalar-only metadata cache without materializing heavy collections or bodies. */
+    listAllItemMetadataLight() {
+        return listClientItemMetadataLight(this.defaults.path, this.defaults.cwd);
+    }
     /** List items with the MCP/agent compact defaults. */
     list(options = {}) {
         return this.runTyped("list", { options });
@@ -403,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 });
@@ -1396,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
@@ -1639,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") ??
@@ -1658,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();
 }
@@ -1808,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,
@@ -1820,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,
@@ -1925,4 +1934,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=c8f2b88e-1883-5744-868b-3a16f3814813
+//# debugId=a294f940-5bb9-55a4-bf2c-64842a3a177b

package/dist/sdk/schema-migration.js

@@ -7,7 +7,7 @@
  * guarantees.
  */
 
-!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]="c4b4af3b-6ce6-56f7-9665-9e6b2f3d9630")}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]="7d175791-016d-59b6-a44d-a70371f36751")}catch(e){}}();
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -18,6 +18,7 @@ import { parseFieldsFile, serializeFieldsFile, } from "../core/schema/fields-fil
 import { parseItemTypesFile, serializeItemTypesFile, } from "../core/schema/item-types-file.js";
 import { DEFAULT_RUNTIME_SCHEMA_FILE_PATHS, filePathForSchemaSection, normalizeRuntimeSchemaSettings, } from "../core/schema/runtime-schema.js";
 import { parseStatusDefsFile, serializeStatusDefsFile, } from "../core/schema/status-defs-file.js";
+import { normalizeStatusToken } from "../core/schema/status-token.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
@@ -55,9 +56,6 @@ export function deriveSchemaEvolutionMigrationId(requestInput, migrationScope) {
         .slice(0, 20)}`;
 }
 function normalizedRequest(request) {
-    const normalizeToken = (value) => requiredText(value, "source or target")
-        .toLowerCase()
-        .replaceAll(/[\s-]+/g, "_");
     const normalized = request.kind === "rename-type"
         ? {
             kind: request.kind,
@@ -67,16 +65,16 @@ function normalizedRequest(request) {
         : request.kind === "rename-field"
             ? {
                 kind: request.kind,
-                from: normalizeToken(request.from),
-                to: normalizeToken(request.to),
+                from: normalizeStatusToken(requiredText(request.from, "source")),
+                to: normalizeStatusToken(requiredText(request.to, "target")),
                 ...(request.type === undefined
                     ? {}
                     : { type: requiredText(request.type, "type") }),
             }
             : {
                 kind: request.kind,
-                from: normalizeToken(request.from),
-                to: normalizeToken(request.to),
+                from: normalizeStatusToken(requiredText(request.from, "source")),
+                to: normalizeStatusToken(requiredText(request.to, "target")),
             };
     if (normalized.from.toLowerCase() === normalized.to.toLowerCase()) {
         throw new TypeError("Schema migration source and target must differ");
@@ -857,4 +855,4 @@ export const schemaMigrationTestOnly = {
     validateAndStoreMigrationPlan,
 };
 //# sourceMappingURL=schema-migration.js.map
-//# debugId=c4b4af3b-6ce6-56f7-9665-9e6b2f3d9630
+//# debugId=7d175791-016d-59b6-a44d-a70371f36751

package/dist/sdk/similarity-scoring.d.ts

@@ -1,3 +1,4 @@
+export { jaccardSimilarity } from "../core/shared/text-normalization.js";
 /** Precomputed title signals reused by bounded batch similarity operations. */
 export interface PreparedSimilarityText {
     /** Canonical title used for exact comparison. */
@@ -20,8 +21,6 @@ export declare function normalizeSimilarityText(value: string): string;
 export declare function tokenizeSimilarityText(value: string): string[];
 /** Precompute every deterministic title signal exactly once for repeated comparisons. */
 export declare function prepareSimilarityText(value: string): PreparedSimilarityText;
-/** Measure set overlap between two token collections. */
-export declare function jaccardSimilarity(leftTokens: readonly string[], rightTokens: readonly string[]): number;
 /** Score two titles through the canonical exact, issue-code, and token signals. */
 export declare function scoreItemSimilarity(leftTitle: string, rightTitle: string): ItemSimilarityScore;
 /** Score two precomputed title representations without repeating normalization or tokenization. */