@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/sdk/query/search-contracts.js

@@ -4,83 +4,13 @@
  * Owns search input parsing, output projection contracts, and tuning defaults.
  */
 
-!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]="e737cdf9-734c-5010-864f-60e8052dd9c1")}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]="d20ab01b-a8ae-5fe8-988a-d05fe87951f6")}catch(e){}}();
 import { coerceNumberInRange } from "../../core/shared/primitives.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
 import { resolveIsoOrRelative } from "../../core/shared/time.js";
 import { renderPmCommand } from "../command-line.js";
-const DEFAULT_COMPACT_SEARCH_FIELDS = [
-    "id",
-    "title",
-    "status",
-    "type",
-    "priority",
-    "updated_at",
-    "score",
-    "matched_fields",
-];
-const SEARCH_HIT_FIELD_KEYS = new Set([
-    "score",
-    "matched_fields",
-    "highlights",
-]);
-const SEARCH_ITEM_FIELD_KEYS = new Set([
-    "id",
-    "title",
-    "description",
-    "type",
-    "status",
-    "priority",
-    "tags",
-    "created_at",
-    "updated_at",
-    "deadline",
-    "assignee",
-    "author",
-    "estimated_minutes",
-    "acceptance_criteria",
-    "dependencies",
-    "comments",
-    "notes",
-    "learnings",
-    "reminders",
-    "events",
-    "files",
-    "tests",
-    "docs",
-    "close_reason",
-    "parent",
-    "reviewer",
-    "risk",
-    "confidence",
-    "sprint",
-    "release",
-    "blocked_by",
-    "blocked_reason",
-    "reporter",
-    "severity",
-    "environment",
-    "repro_steps",
-    "resolution",
-    "expected_result",
-    "actual_result",
-    "affected_version",
-    "fixed_version",
-    "component",
-    "regression",
-    "customer_impact",
-    "definition_of_ready",
-    "order",
-    "rank",
-    "goal",
-    "objective",
-    "value",
-    "impact",
-    "outcome",
-    "why_now",
-    "plan",
-]);
+import { EXIT_CODE, PmCliError } from "../runtime-primitives.js";
+import { DEFAULT_COMPACT_SEARCH_FIELDS, listSearchProjectionFields, } from "./projection-contracts.js";
+export { DEFAULT_COMPACT_SEARCH_FIELDS, SEARCH_HIT_FIELD_KEYS, SEARCH_ITEM_FIELD_KEYS, listSearchProjectionFields, } from "./projection-contracts.js";
 /** Parse the configured search execution mode. */
 export function parseSearchMode(raw) {
     if (raw === undefined)
@@ -155,7 +85,7 @@ function parseFieldSelectors(raw) {
     return [...new Set(selectors)];
 }
 /** Resolve mutually exclusive compact, full, or explicit-field projection. */
-export function parseSearchProjection(options) {
+export function parseSearchProjection(options, query = "<query>") {
     const compactRequested = options.compact === true;
     const fullRequested = options.full === true;
     const fieldSelectors = parseFieldSelectors(options.fields);
@@ -163,7 +93,13 @@ export function parseSearchProjection(options) {
         Number(fullRequested) +
         Number(fieldSelectors !== undefined);
     if (enabledModes > 1) {
-        throw new PmCliError("Search projection options are mutually exclusive. Use one of --compact, --full, or --fields.", EXIT_CODE.USAGE);
+        throw new PmCliError("Search projection options are mutually exclusive. Use one of --compact, --full, or --fields.", EXIT_CODE.USAGE, {
+            code: "projection_options_mutually_exclusive",
+            recovery: {
+                suggested_retry: renderPmCommand(["search", query, "--full"]),
+                suggested_retry_args: ["search", query, "--full"],
+            },
+        });
     }
     if (compactRequested) {
         return { mode: "compact", fields: [...DEFAULT_COMPACT_SEARCH_FIELDS] };
@@ -178,20 +114,14 @@ export function parseSearchProjection(options) {
 export function validateSearchProjectionFields(projection, runtimeFieldRegistry, query = "<query>") {
     if (projection.mode !== "fields")
         return;
-    const runtimeKeys = new Set(runtimeFieldRegistry.definitions.flatMap((field) => [
+    const allowedValues = listSearchProjectionFields(runtimeFieldRegistry.definitions.flatMap((field) => [
         field.key,
         field.metadata_key,
     ]));
-    const allowedValues = new Set([
-        ...SEARCH_HIT_FIELD_KEYS,
-        ...SEARCH_ITEM_FIELD_KEYS,
-        ...[...SEARCH_ITEM_FIELD_KEYS].map((field) => `item.${field}`),
-        ...runtimeKeys,
-        ...[...runtimeKeys].map((field) => `item.${field}`),
-    ]);
+    const allowed = new Set(allowedValues);
     const unknown = projection.fields.filter((field) => {
         const normalized = field.trim();
-        return !allowedValues.has(normalized);
+        return !allowed.has(normalized);
     });
     if (unknown.length > 0) {
         const suggestedRetryArguments = [
@@ -201,6 +131,7 @@ export function validateSearchProjectionFields(projection, runtimeFieldRegistry,
             "id,title,status,score",
         ];
         throw new PmCliError(`Unknown search --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
+            code: "unknown_field_projection",
             examples: [
                 "pm search <query> --fields id,title,status,score",
                 "pm search <query> --fields id,title,item.description,matched_fields",
@@ -209,7 +140,7 @@ export function validateSearchProjectionFields(projection, runtimeFieldRegistry,
                 "Use item.<field> for explicit item metadata fields, or run pm search --help for projection examples.",
             ],
             recovery: {
-                allowed_values: [...allowedValues].sort(),
+                allowed_values: allowedValues,
                 suggested_retry: renderPmCommand(suggestedRetryArguments),
                 suggested_retry_args: suggestedRetryArguments,
             },
@@ -297,4 +228,4 @@ export function resolveSearchTuning(settings) {
     };
 }
 //# sourceMappingURL=search-contracts.js.map
-//# debugId=e737cdf9-734c-5010-864f-60e8052dd9c1
+//# debugId=d20ab01b-a8ae-5fe8-988a-d05fe87951f6

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

@@ -183,8 +183,23 @@ export declare function collectErrorCauseCodes(error: unknown): string;
  */
 export declare function classifyImplicitSemanticFallbackReason(error: unknown): ImplicitSemanticFallbackReason;
 declare function buildExplicitSemanticFallbackWarning(requestedMode: SearchMode, error: unknown): string;
+interface VectorIndexRecoveryRegistrations {
+    commands?: readonly {
+        command: string;
+    }[];
+}
+interface VectorIndexRecovery {
+    command: string;
+    args: string[];
+    follow_up_command?: string;
+    follow_up_args?: string[];
+}
+/** Resolve an executable reindex path from the active extension capability surface. */
+export declare function resolveVectorIndexRecovery(registrations: VectorIndexRecoveryRegistrations | null): VectorIndexRecovery;
 /** Compare the vectorization-status ledger against the filtered corpus and, when the vector index is behind, emit a one-line stderr warning plus a structured `vector_index_stale:N` entry in the JSON warnings array. Best-effort: ledger read failures fall through silently — the existing semantic/hybrid fallback paths cover backend errors. */
 declare function maybeEmitVectorIndexStaleWarning(pmRoot: string, filteredDocuments: ItemDocument[], warnings: string[]): Promise<void>;
+/** Format token-efficient vector-index staleness and executable recovery warnings. */
+export declare function formatVectorIndexRecoveryWarnings(staleCount: number, recovery: VectorIndexRecovery): string[];
 /** Public contract for test only search command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlySearchCommand: {
     applyFilters: typeof applyFilters;

package/dist/sdk/query/search.js

@@ -4,7 +4,8 @@
  * Implements the pm search 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]="0582c462-43fc-563c-b209-d6e3c39948f4")}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]="a4117e19-af3e-50f5-b3cc-86c39aa4b439")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -23,7 +24,6 @@ import { readVectorizationStatusLedger } from "../../core/search/cache.js";
 import { buildEventCorpus, buildPlanFlatCorpus, buildReminderCorpus, buildSearchCorpus, resolveSearchCorpusFields, } from "../../core/search/corpus.js";
 import { buildBm25Index, flattenSearchCorpusText, resolveBm25Params, scoreBm25Query, tokenizeBm25, } from "../../core/search/bm25.js";
 import { collectStaleVectorizationIds } from "../../core/search/staleness.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { toItemRecord } from "../../core/item/item-record.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -40,7 +40,7 @@ import { tokenizeAlphaNumeric } from "../../core/shared/text-normalization.js";
 import { compareTimestampStrings, matchesTimestampFilters, nowIso, } from "../../core/shared/time.js";
 import { listAllDocumentCandidatesCached } from "../../core/store/item-metadata-cache.js";
 import { listAllItemMetadata } from "../../core/store/item-store.js";
-import { getItemPath, getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { getItemPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { resolveSearchPage } from "./search-pagination.js";
 import { normalizeSearchPhrase, parseMinScoreOverride, parseSearchBoolean, parseSearchDeadline, parseSearchMatchMode, parseSearchMode, parseSearchProjection, parseSearchTokens, parseSemanticWeightOverride, parseTimestampWindow, resolveHybridSemanticWeight, resolveSearchMaxResults, resolveSearchScoreThreshold, resolveSearchTuning, validateSearchProjectionFields, } from "./search-contracts.js";
@@ -128,6 +128,21 @@ function buildExplicitSemanticFallbackWarning(requestedMode, error) {
     const reason = classifyImplicitSemanticFallbackReason(error);
     return `search_${requestedMode}_fallback:${reason}:using_keyword_mode`;
 }
+/** Resolve an executable reindex path from the active extension capability surface. */
+export function resolveVectorIndexRecovery(registrations) {
+    const hasReindex = registrations?.commands?.some((registration) => registration.command.trim() === "reindex") === true;
+    return hasReindex
+        ? {
+            command: "pm reindex --mode hybrid",
+            args: ["reindex", "--mode", "hybrid"],
+        }
+        : {
+            command: "pm install search-advanced --project",
+            args: ["install", "search-advanced", "--project"],
+            follow_up_command: "pm reindex --mode hybrid",
+            follow_up_args: ["reindex", "--mode", "hybrid"],
+        };
+}
 /** Compare the vectorization-status ledger against the filtered corpus and, when the vector index is behind, emit a one-line stderr warning plus a structured `vector_index_stale:N` entry in the JSON warnings array. Best-effort: ledger read failures fall through silently — the existing semantic/hybrid fallback paths cover backend errors. */
 async function maybeEmitVectorIndexStaleWarning(pmRoot, filteredDocuments, warnings) {
     try {
@@ -142,15 +157,26 @@ async function maybeEmitVectorIndexStaleWarning(pmRoot, filteredDocuments, warni
         if (staleIds.length === 0) {
             return;
         }
-        warnings.push(`vector_index_stale:${staleIds.length}`);
+        const recovery = resolveVectorIndexRecovery(getActiveExtensionRegistrations());
+        warnings.push(...formatVectorIndexRecoveryWarnings(staleIds.length, recovery));
         /* c8 ignore start -- singular/plural warning text branches are cosmetic and validated in integration UX tests */
-        process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length === 1 ? " is" : "s are"} new or modified since the last reindex and ${staleIds.length === 1 ? "is" : "are"} NOT in the semantic index yet — they will be missing from semantic/hybrid results until you run 'pm reindex --mode hybrid'. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)\n`);
+        process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length === 1 ? " is" : "s are"} new or modified since the last reindex and ${staleIds.length === 1 ? "is" : "are"} NOT in the semantic index yet — run '${recovery.command}'${recovery.follow_up_command ? `, then '${recovery.follow_up_command}'` : ""}. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)\n`);
         /* c8 ignore stop */
     }
     catch {
         // Best-effort: missing/unreadable ledger is not a query-blocking concern.
     }
 }
+/** Format token-efficient vector-index staleness and executable recovery warnings. */
+export function formatVectorIndexRecoveryWarnings(staleCount, recovery) {
+    return [
+        `vector_index_stale:${staleCount}`,
+        `vector_index_recovery:${recovery.args.join(" ")}`,
+        ...(recovery.follow_up_args
+            ? [`vector_index_recovery_follow_up:${recovery.follow_up_args.join(" ")}`]
+            : []),
+    ];
+}
 /** Public contract for test only search command, shared by SDK and presentation-layer consumers. */
 export const _testOnlySearchCommand = {
     applyFilters,
@@ -1539,15 +1565,13 @@ function prepareSearchInput(rawQuery, rawOptions) {
         tokens: parseSearchTokens(query),
         normalizedQuery: normalizeSearchPhrase(query),
         limit: parseLimit(options.limit),
-        projection: parseSearchProjection(options),
+        projection: parseSearchProjection(options, rawQuery),
         modeWasExplicit: typeof options.mode === "string" && options.mode.trim().length > 0,
     };
 }
 async function resolveSearchRuntimeContext(prepared, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const storedSettings = await readSettings(pmRoot);
     const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
@@ -1961,4 +1985,4 @@ export async function runSearch(rawQuery, rawOptions, global) {
     return withSearchWorkspaceMemory(buildSearchResultForHits(response, projectedItems, total, page.limited.length, effectiveProjection, page.pageExtras), workspaceMemoryResult);
 }
 //# sourceMappingURL=search.js.map
-//# debugId=0582c462-43fc-563c-b209-d6e3c39948f4
+//# debugId=a4117e19-af3e-50f5-b3cc-86c39aa4b439

package/dist/sdk/relationship-kinds/contract.d.ts

@@ -15,12 +15,20 @@ export type RelationshipTemporalOrder = "source_after_target";
 export type RelationshipPrecedence = "source_before_target" | "target_before_source";
 /** Endpoint that represents the structural parent for hierarchy kinds. */
 export type RelationshipHierarchyDirection = "source_parent" | "target_parent";
+/** Closure family that gives a relationship its default traversal vocabulary. */
+export type RelationshipTraversalFamily = "hierarchy" | "ordering" | "semantic" | "association";
+/** Direction in which an edge can carry a node toward a declared outcome. */
+export type RelationshipOutcomeTraversal = "source_to_target" | "target_to_source" | "both";
 /** Versioned semantic definition for a built-in or application-defined edge kind. */
 export interface RelationshipKindDefinition {
     /** Canonical, case-insensitive kind identifier. */
     kind: string;
     /** Whether traversing source to target has distinct meaning from the reverse. */
     direction: RelationshipDirection;
+    /** Default closure vocabulary; omitted custom definitions infer it from legacy flags. */
+    traversal?: RelationshipTraversalFamily;
+    /** Direction this kind contributes to typed outcome reachability, when any. */
+    outcomeTraversal?: RelationshipOutcomeTraversal;
     /** Optional canonical kind used when traversing a directed edge in reverse. */
     inverse?: string;
     /** Whether the kind participates in execution-order cycle checks. */

package/dist/sdk/relationship-kinds/contract.js

@@ -5,19 +5,19 @@
  */
 /** Stable built-in relationship ontology without graph or storage dependencies. */
 
-!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]="825e1dd9-4168-56f6-9183-b8cf75314b73")}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]="aa7d04c7-b057-569c-816a-f53322c74261")}catch(e){}}();
 export const BUILTIN_RELATIONSHIP_KINDS = [
-    { kind: "blocked_by", direction: "directed", inverse: "blocks", ordering: true, precedence: "target_before_source", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["depends_on"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "blocks", direction: "directed", inverse: "blocked_by", ordering: true, precedence: "source_before_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "parent", direction: "directed", inverse: "child", ordering: false, hierarchy: true, hierarchyDirection: "target_parent", outgoing: "one", incoming: "many", lifecycle: "supersedable", aliases: ["child_of", "epic"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "child", direction: "directed", inverse: "parent", ordering: false, hierarchy: true, hierarchyDirection: "source_parent", outgoing: "many", incoming: "one", lifecycle: "supersedable", aliases: ["parent_child", "task"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "related", direction: "undirected", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["related_to"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "discovered_from", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "incident_from", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "implements", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "recurs_from", direction: "directed", ordering: false, temporalOrder: "source_after_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "verifies", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "supersedes", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "supersedable", compatibilityVersion: 1, allowSelf: false },
+    { kind: "blocked_by", direction: "directed", traversal: "ordering", inverse: "blocks", ordering: true, precedence: "target_before_source", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["depends_on"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "blocks", direction: "directed", traversal: "ordering", inverse: "blocked_by", ordering: true, precedence: "source_before_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "parent", direction: "directed", traversal: "hierarchy", outcomeTraversal: "source_to_target", inverse: "child", ordering: false, hierarchy: true, hierarchyDirection: "target_parent", outgoing: "one", incoming: "many", lifecycle: "supersedable", aliases: ["child_of", "epic"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "child", direction: "directed", traversal: "hierarchy", outcomeTraversal: "target_to_source", inverse: "parent", ordering: false, hierarchy: true, hierarchyDirection: "source_parent", outgoing: "many", incoming: "one", lifecycle: "supersedable", aliases: ["parent_child", "task"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "related", direction: "undirected", traversal: "association", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["related_to"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "discovered_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "incident_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "implements", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "recurs_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, temporalOrder: "source_after_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "verifies", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "supersedes", direction: "directed", traversal: "semantic", outcomeTraversal: "both", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "supersedable", compatibilityVersion: 1, allowSelf: false },
 ];
 //# sourceMappingURL=contract.js.map
-//# debugId=825e1dd9-4168-56f6-9183-b8cf75314b73
+//# debugId=aa7d04c7-b057-569c-816a-f53322c74261

package/dist/sdk/relationships.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Dependency, ItemMetadata } from "../types/index.js";
 import { type RelationshipKindDefinition } from "./relationship-kinds/contract.js";
-export { BUILTIN_RELATIONSHIP_KINDS, type RelationshipCardinality, type RelationshipDirection, type RelationshipHierarchyDirection, type RelationshipKindDefinition, type RelationshipLifecycle, type RelationshipPrecedence, type RelationshipTemporalOrder, } from "./relationship-kinds/contract.js";
+export { BUILTIN_RELATIONSHIP_KINDS, type RelationshipCardinality, type RelationshipDirection, type RelationshipHierarchyDirection, type RelationshipKindDefinition, type RelationshipLifecycle, type RelationshipOutcomeTraversal, type RelationshipPrecedence, type RelationshipTemporalOrder, type RelationshipTraversalFamily, } from "./relationship-kinds/contract.js";
 /** One normalized relationship edge indexed by the graph kernel. */
 export interface RelationshipEdge {
     /** Source node identifier. */

package/dist/sdk/relationships.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]="7f733de4-104b-50a9-9c0a-cd9850bfcd78")}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]="b1c32b57-0231-5bea-ade4-99247504f938")}catch(e){}}();
 import { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 export { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 function normalizeKind(kind) {
@@ -82,6 +82,16 @@ function assertRelationshipKindSemantics(definition, kind) {
         throw new TypeError(`Invalid relationship lifecycle for ${kind}`);
     if (typeof definition.allowSelf !== "boolean")
         throw new TypeError(`Invalid relationship self-edge flag for ${kind}`);
+    if (definition.traversal !== undefined &&
+        !["hierarchy", "ordering", "semantic", "association"].includes(definition.traversal))
+        throw new TypeError(`Invalid relationship traversal family for ${kind}`);
+    if (definition.outcomeTraversal !== undefined &&
+        !["source_to_target", "target_to_source", "both"].includes(definition.outcomeTraversal))
+        throw new TypeError(`Invalid outcome traversal for ${kind}`);
+    if (definition.direction === "undirected" &&
+        definition.outcomeTraversal !== undefined &&
+        definition.outcomeTraversal !== "both")
+        throw new TypeError(`Undirected relationship kind cannot declare directional outcome traversal: ${kind}`);
 }
 /** Validate application payload-schema and compatibility-alias containers. */
 function assertRelationshipKindPayload(definition, kind) {
@@ -129,6 +139,14 @@ export class RelationshipKindRegistry {
         const normalized = Object.freeze({
             ...definition,
             kind,
+            traversal: definition.traversal ??
+                (definition.hierarchy
+                    ? "hierarchy"
+                    : definition.ordering
+                        ? "ordering"
+                        : definition.direction === "undirected"
+                            ? "association"
+                            : "semantic"),
             hierarchy: definition.hierarchy ?? false,
             inverse,
             aliases: Object.freeze(aliases),
@@ -552,4 +570,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=7f733de4-104b-50a9-9c0a-cd9850bfcd78
+//# debugId=b1c32b57-0231-5bea-ade4-99247504f938

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

@@ -72,7 +72,7 @@ export { splitCommaList } from "../core/shared/split-comma-list.js";
 export { compareTimestampStrings, nowIso, resolveIsoOrRelative, } from "../core/shared/time.js";
 export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 export { type CachedDocumentCandidate, listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
-export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * 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]="a678b9f8-ba36-5127-877f-96bb4acc38c5")}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]="1bcfba24-e761-571c-96e6-36bbc12d2814")}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";
@@ -73,7 +73,7 @@ export { splitCommaList } from "../core/shared/split-comma-list.js";
 export { compareTimestampStrings, nowIso, resolveIsoOrRelative, } from "../core/shared/time.js";
 export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js";
 export { listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
-export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
+export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
 export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
@@ -81,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=a678b9f8-ba36-5127-877f-96bb4acc38c5
+//# debugId=1bcfba24-e761-571c-96e6-36bbc12d2814

package/dist/sdk/runtime.d.ts

@@ -23,6 +23,7 @@ import { type AggregateOptions, type AggregateResult } from "./query/aggregate.j
 import { type UpgradeCommandOptions, type UpgradeResult } from "./governance/upgrade.js";
 import { type CreateResult } from "./lifecycle/create.js";
 import { type UpdateResult } from "./lifecycle/update.js";
+import type { ReopenCommandOptions, ReopenResult } from "./lifecycle/reopen.js";
 import { type PlanCommandOptions, type PlanCommandResult, type PlanSubcommand } from "./lifecycle/plan.js";
 import { type ContextOptions, type ContextResult } from "./query/context.js";
 import { type NextOptions, type NextResult } from "./query/next.js";
@@ -93,6 +94,7 @@ export { runFocus, type FocusOptions, type FocusResult, } from "./lifecycle/focu
 export { runRestore, type RestoreCommandOptions, type RestoreResult, } from "./lifecycle/restore.js";
 export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, type CloseOperationOptions, type CloseOperationResult, type TerminalOrderingMutation, type TerminalReasonInput, type TerminalReasonResolution, type TerminalReasonSource, type TerminalTransitionPolicy, } from "./lifecycle-policy.js";
 export { runUpdate, type UpdateCommandOptions } from "./lifecycle/update.js";
+export { runReopen, type PreviousTerminalEvidence, type RecurrenceReceipt, type ReopenCommandOptions, type ReopenResult } from "./lifecycle/reopen.js";
 export { NEXT_OUTPUT_VALUES, runNext, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult, } from "./query/next.js";
 export { runSearch, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult, } from "./query/search.js";
 export { runStats, type StatsCommandOptions, type StatsResult, } from "./stats.js";
@@ -293,6 +295,8 @@ export declare class PmClient {
     create(options?: PmCreateActionOptions): Promise<CreateResult>;
     /** Update an item using the same mutation path as `pm update`. Options are contract-typed (pm-x29o): unknown keys and non-scalar values fail `tsc`; runtime-schema custom fields go through the repeatable `field` option, and {@link PmClient.run} stays the wide escape hatch. */
     update(id: string, options?: PmUpdateActionOptions): Promise<UpdateResult>;
+    /** Reopen terminal work as a recurrence through the canonical update path. */
+    reopen(id: string, reason: string, options?: ReopenCommandOptions): Promise<ReopenResult>;
     /** Close an item using the same mutation path as `pm close`. Options are contract-typed (pm-x29o); the close reason is the positional parameter, so the option bag omits `reason`/`text`. */
     close(id: string, reason: string, options?: PmClientCloseActionOptions): Promise<CloseResult>;
     /** Claim an item using the same mutation path as `pm claim`. */
@@ -469,6 +473,8 @@ export declare function historyCompactBulk(options: HistoryCompactBulkCommandOpt
 export declare function create(options?: PmCreateActionOptions, clientOptions?: PmClientOptions): Promise<CreateResult>;
 /** Update an item without constructing a reusable client. */
 export declare function update(id: string, options?: PmUpdateActionOptions, clientOptions?: PmClientOptions): Promise<UpdateResult>;
+/** Reopen terminal work as a recurrence without constructing a reusable client. */
+export declare function reopen(id: string, reason: string, options?: ReopenCommandOptions, clientOptions?: PmClientOptions): Promise<ReopenResult>;
 /** Close an item without constructing a reusable client. */
 export declare function close(id: string, reason: string, options?: PmClientCloseActionOptions, clientOptions?: PmClientOptions): Promise<CloseResult>;
 /** Claim an item without constructing a reusable client. */

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]="95764dd9-1b0d-5732-9f10-b13b334ce27d")}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]="c770afea-3eb6-5476-ba07-8ec1c5d9c699")}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";
@@ -70,6 +70,7 @@ import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-at
 import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
+import { runMcpCloseAction, runMcpReopenAction } from "./lifecycle/mcp-actions.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";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
@@ -119,6 +120,7 @@ export { runFocus, } from "./lifecycle/focus.js";
 export { runRestore, } from "./lifecycle/restore.js";
 export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, } from "./lifecycle-policy.js";
 export { runUpdate } from "./lifecycle/update.js";
+export { runReopen } from "./lifecycle/reopen.js";
 export { NEXT_OUTPUT_VALUES, runNext, } from "./query/next.js";
 export { runSearch, } from "./query/search.js";
 export { runStats, } from "./stats.js";
@@ -536,6 +538,15 @@ export class PmClient {
             ...splitFullClientMutationOptions(options),
         });
     }
+    /** Reopen terminal work as a recurrence through the canonical update path. */
+    reopen(id, reason, options = {}) {
+        return this.runTyped("item-reopen", {
+            id,
+            reason,
+            fullChangedFields: true,
+            options,
+        });
+    }
     /** Close an item using the same mutation path as `pm close`. Options are contract-typed (pm-x29o); the close reason is the positional parameter, so the option bag omits `reason`/`text`. */
     close(id, reason, options = {}) {
         return this.runTyped("close", {
@@ -908,6 +919,10 @@ export function create(options = {}, clientOptions = {}) {
 export function update(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).update(id, options);
 }
+/** Reopen terminal work as a recurrence without constructing a reusable client. */
+export function reopen(id, reason, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).reopen(id, reason, options);
+}
 /** Close an item without constructing a reusable client. */
 export function close(id, reason, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).close(id, reason, options);
@@ -1392,18 +1407,6 @@ async function runMcpUpdateAction(ctx) {
         idOnly,
     });
 }
-async function runMcpCloseAction(ctx) {
-    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
-    const closeReason = readString(ctx.args, "reason") ??
-        readString(ctx.args, "text") ??
-        readString(runnerOptions, "reason") ??
-        readString(runnerOptions, "text");
-    return projectMutationResult(await runClose(requireMcpItemId(ctx, runnerOptions), closeReason, runnerOptions, ctx.global), {
-        changedFields,
-        compactEnvelope: changedFields === "compact" && !idOnly,
-        idOnly,
-    });
-}
 function runMcpCommentsAction(ctx) {
     const commentOptions = normalizeAnnotationTransportOptions(ctx.options);
     const isListing = commentOptions.add === undefined &&
@@ -1808,6 +1811,7 @@ const SDK_ACTION_HANDLERS = {
     copy: runMcpCopyAction,
     focus: (ctx) => runFocus(ctx.id, { clear: ctx.options.clear === true || ctx.args.clear === true }, ctx.global),
     update: runMcpUpdateAction,
+    "item-reopen": runMcpReopenAction,
     restore: runMcpRestoreAction,
     claim: (ctx) => ctx.options.next === true || ctx.args.next === true
         ? runClaimNext(ctx.force, ctx.global, { ...ctx.options, ...ctx.args }, { ...ctx.options, ...ctx.args })
@@ -1940,4 +1944,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=95764dd9-1b0d-5732-9f10-b13b334ce27d
+//# debugId=c770afea-3eb6-5476-ba07-8ec1c5d9c699

package/dist/sdk/schema-migration.js

@@ -7,11 +7,12 @@
  * 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]="cd777de3-665f-5e01-ac98-8986f2a5a4c2")}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]="60738c1f-3b44-5f8a-82c9-99d2b2de1e51")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isFileMissingError, pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+import { isFileMissingError, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 import { appendWorkspaceHistoryChange } from "../core/history/workspace-history.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { parseFieldsFile, serializeFieldsFile, } from "../core/schema/fields-file.js";
@@ -21,7 +22,7 @@ import { parseStatusDefsFile, serializeStatusDefsFile, } from "../core/schema/st
 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";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -725,9 +726,7 @@ async function appendSchemaReferenceHistory(params) {
 export async function runSchemaEvolutionMigration(requestInput, options, global) {
     const request = normalizedRequest(requestInput);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const migrationId = options.migrationId === undefined
         ? deriveSchemaEvolutionMigrationId(request, await fs.realpath(pmRoot))
         : requiredMigrationId(options.migrationId);
@@ -855,4 +854,4 @@ export const schemaMigrationTestOnly = {
     validateAndStoreMigrationPlan,
 };
 //# sourceMappingURL=schema-migration.js.map
-//# debugId=cd777de3-665f-5e01-ac98-8986f2a5a4c2
+//# debugId=60738c1f-3b44-5f8a-82c9-99d2b2de1e51