@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/dist/sdk/item-children.js

@@ -7,10 +7,12 @@
  * projection contract.
  */
 
-!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]="2e14b978-95c9-5922-b8cb-c49d24e6f8c4")}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]="4b4d4bb6-8a17-5544-a18c-ad3fc49a759e")}catch(e){}}();
 import { isTerminalStatus } from "../core/item/status.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "./graph/assembly.js";
+import { collectHierarchyRelations, indexHierarchyRelations, } from "./graph/hierarchy-integrity.js";
 /** Maximum corpus rows inspected by one child projection. */
 export const MAX_CHILD_PROJECTION_ITEMS = 1_000_000;
 /** Default number of child summaries retained inline. */
@@ -25,8 +27,7 @@ export function buildItemChildrenRollup(parentId, corpus, statusRegistry, sample
     }
     const normalizedParentId = parentId.trim().toLowerCase();
     const byStatus = {};
-    const children = [];
-    let active = 0;
+    const candidates = [];
     let scanned = 0;
     for (const candidate of corpus) {
         scanned += 1;
@@ -40,11 +41,23 @@ export function buildItemChildrenRollup(parentId, corpus, statusRegistry, sample
                 ],
             });
         }
-        if (candidate.parent?.trim().toLowerCase() !== normalizedParentId) {
-            continue;
+        candidates.push(candidate);
+    }
+    const itemById = new Map(candidates.map((candidate) => [
+        candidate.id.trim().toLowerCase(),
+        candidate,
+    ]));
+    const hierarchyIndexes = indexHierarchyRelations(collectHierarchyRelations(candidates, resolveWorkspaceRelationshipKindRegistry()));
+    const childIds = new Set(hierarchyIndexes.children_by_parent.get(normalizedParentId) ?? []);
+    for (const candidate of candidates) {
+        if (candidate.parent?.trim().toLowerCase() === normalizedParentId) {
+            childIds.add(candidate.id.trim().toLowerCase());
         }
-        children.push(candidate);
-        const status = candidate.status.trim().toLowerCase();
+    }
+    const children = [...childIds].map((childId) => itemById.get(childId));
+    let active = 0;
+    for (const child of children) {
+        const status = child.status.trim().toLowerCase();
         byStatus[status] = (byStatus[status] ?? 0) + 1;
         if (!isTerminalStatus(status, statusRegistry)) {
             active += 1;
@@ -75,4 +88,4 @@ export function buildItemChildrenRollup(parentId, corpus, statusRegistry, sample
     };
 }
 //# sourceMappingURL=item-children.js.map
-//# debugId=2e14b978-95c9-5922-b8cb-c49d24e6f8c4
+//# debugId=4b4d4bb6-8a17-5544-a18c-ad3fc49a759e

package/dist/sdk/lifecycle/append.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module cli/commands/append
- *
- * Implements the pm append command surface and its agent-facing runtime behavior.
- */
 import { type GlobalOptions } from "../runtime-primitives.js";
 /** Documents the append command options payload exchanged by command, SDK, and package integrations. */
 export interface AppendCommandOptions {

package/dist/sdk/lifecycle/append.js

@@ -4,8 +4,9 @@
  * Implements the pm append 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]="9e3ba7e9-8822-53ba-981e-e177be5219f3")}catch(e){}}();
-import { pathExists, EXIT_CODE, PmCliError, resolveAuthor, toItemRecord, createStdinTokenResolver, mutateItem, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
+!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]="73184370-6517-533e-90db-536893402616")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { EXIT_CODE, PmCliError, resolveAuthor, toItemRecord, createStdinTokenResolver, mutateItem, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 /** Implements run append for the public runtime surface of this module. */
 export async function runAppend(id, options, global) {
     if (options.body === undefined) {
@@ -13,9 +14,7 @@ export async function runAppend(id, options, global) {
     }
     const stdinResolver = createStdinTokenResolver();
     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 settings = await readSettings(pmRoot);
     const author = resolveAuthor(options.author, settings.author_default);
     // options.body is guaranteed defined by the guard above, so resolveValue returns a defined string.
@@ -52,4 +51,4 @@ export async function runAppend(id, options, global) {
     };
 }
 //# sourceMappingURL=append.js.map
-//# debugId=9e3ba7e9-8822-53ba-981e-e177be5219f3
+//# debugId=73184370-6517-533e-90db-536893402616

package/dist/sdk/lifecycle/claim.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module cli/commands/claim
- *
- * Implements the pm claim command surface and its agent-facing runtime behavior.
- */
 import { type GlobalOptions } from "../runtime-primitives.js";
 import { type NextRecommendation, type NextOptions } from "../query/next.js";
 /** Stable warning/error code for an exhausted atomic next-work walk. */

package/dist/sdk/lifecycle/claim.js

@@ -4,8 +4,9 @@
  * Implements the pm claim 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]="f70f1329-4dfb-5625-ae0a-66c858d88f7b")}catch(e){}}();
-import { pathExists, resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
+!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]="1a61bf25-e320-5adc-8f5a-a427bc89af1a")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
 import { wrapOwnershipConflict } from "../annotations.js";
 import { describeItemOwnershipConflict } from "../ownership-source.js";
 import { runNext, } from "../query/next.js";
@@ -26,9 +27,7 @@ export function isAlreadyClaimedError(error) {
 /** Implements run claim for the public runtime surface of this module. */
 export async function runClaim(id, force, global, options = {}) {
     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 settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const author = resolveAuthor(options.author, settings.author_default);
@@ -184,9 +183,7 @@ export async function claimNextFromRecommendations(recommendations, force, globa
 /** Implements run release for the public runtime surface of this module. */
 export async function runRelease(id, force, global, options = {}) {
     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 settings = await readSettings(pmRoot);
     const author = resolveAuthor(options.author, settings.author_default);
     const claimPrincipal = resolveClaimPrincipal(author);
@@ -237,4 +234,4 @@ export async function runRelease(id, force, global, options = {}) {
     };
 }
 //# sourceMappingURL=claim.js.map
-//# debugId=f70f1329-4dfb-5625-ae0a-66c858d88f7b
+//# debugId=1a61bf25-e320-5adc-8f5a-a427bc89af1a

package/dist/sdk/lifecycle/close-many.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module cli/commands/close-many
- *
- * Implements the pm close many command surface and its agent-facing runtime behavior.
- */
 import { type GlobalOptions, readSettings } from "../runtime-primitives.js";
 import { type ListOptions } from "../query/list.js";
 import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";

package/dist/sdk/lifecycle/close-many.js

@@ -4,8 +4,9 @@
  * Implements the pm close many 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]="4da07a98-855e-59cf-a6a4-2f59a8b3c0bd")}catch(e){}}();
-import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, resolveAuthor, nowIso, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
+!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]="a7113374-b169-5f92-9c20-075a47520440")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, resolveAuthor, nowIso, listAllItemMetadataLight, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { runClose } from "./close.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList } from "../query/list.js";
@@ -336,9 +337,7 @@ async function resolveCloseManyCheckpointInfo(params) {
 /** Implements run close many for the public runtime surface of this module. */
 export async function runCloseMany(options, 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 settings = await readSettings(pmRoot);
     const dryRun = options.dryRun === true;
     const rollbackId = resolveCloseManyRollbackId(options);
@@ -428,4 +427,4 @@ export const _testOnly = {
     resolveReason,
 };
 //# sourceMappingURL=close-many.js.map
-//# debugId=4da07a98-855e-59cf-a6a4-2f59a8b3c0bd
+//# debugId=a7113374-b169-5f92-9c20-075a47520440

package/dist/sdk/lifecycle/close.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/lifecycle/close
- *
- * Implements the pm close command surface and its agent-facing runtime behavior.
- */
 import { type GlobalOptions } from "../runtime-primitives.js";
 import { collectBlockedByIds } from "../actionability.js";
 import { type CloseOperationOptions, type CloseOperationResult } from "../lifecycle-policy.js";

package/dist/sdk/lifecycle/close.js

@@ -4,8 +4,9 @@
  * Implements the pm close 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]="83affe54-a56c-5d84-b6b0-9634d4238ff5")}catch(e){}}();
-import { pathExists, toItemRecord, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, resolveIsoOrRelative, shouldCompletePlanOnClose, getActiveExtensionRegistrations, } from "../runtime-primitives.js";
+!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]="781b5118-7b07-53c7-802f-c889cb797a96")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { toItemRecord, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, resolveIsoOrRelative, shouldCompletePlanOnClose, getActiveExtensionRegistrations, } from "../runtime-primitives.js";
 import { collectBlockedByIds, indexBlockedByIds } from "../actionability.js";
 import { applyTerminalOrderingPolicy, requireTerminalReason, } from "../lifecycle-policy.js";
 import { renderPmCommand } from "../command-line.js";
@@ -367,9 +368,7 @@ export const _testOnlyCloseCommand = {
 /** Close one item through the SDK-owned lifecycle transaction and policy. */
 export async function closeItem(id, closeReasonText, options, 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 settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const author = resolveAuthor(options.author, settings.author_default);
@@ -458,4 +457,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=83affe54-a56c-5d84-b6b0-9634d4238ff5
+//# debugId=781b5118-7b07-53c7-802f-c889cb797a96

package/dist/sdk/lifecycle/copy.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/lifecycle/copy
- *
- * Implements the SDK-owned copy lifecycle operation shared by every surface.
- */
 import { type GlobalOptions } from "../runtime-primitives.js";
 import { type SimilarityAdvisory } from "../similarity.js";
 import type { ItemMetadata } from "../../types/index.js";

package/dist/sdk/lifecycle/copy.js

@@ -4,8 +4,9 @@
  * Implements the SDK-owned copy lifecycle operation shared by every surface.
  */
 
-!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]="4eb2056a-4444-514a-a0db-79b8875c3d65")}catch(e){}}();
-import { pathExists, removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, canonicalDocument, serializeItemDocument, acquireLock, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, collectRegisteredItemFieldNames, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, nowIso, PmCliError, resolveItemTypeRegistry, buildItemNotFoundError, locateItem, readLocatedItem, getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+!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]="b59e8e54-f9e0-5cdb-bc59-6dcbf67f278d")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, canonicalDocument, serializeItemDocument, acquireLock, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnWriteHooks, collectRegisteredItemFieldNames, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, nowIso, PmCliError, resolveItemTypeRegistry, buildItemNotFoundError, locateItem, readLocatedItem, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { evaluateSimilarityGovernance, similarityAdvisoryWarnings, } from "../similarity.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
 function buildChangedFields(itemMetadata, body) {
@@ -29,9 +30,7 @@ function buildCopyMessage(sourceId, message) {
 /** Implements run copy for the public runtime surface of this module. */
 export async function runCopy(sourceId, options, 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 settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const located = await locateItem(pmRoot, sourceId, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
@@ -211,4 +210,4 @@ export async function runCopy(sourceId, options, global) {
     };
 }
 //# sourceMappingURL=copy.js.map
-//# debugId=4eb2056a-4444-514a-a0db-79b8875c3d65
+//# debugId=b59e8e54-f9e0-5cdb-bc59-6dcbf67f278d

package/dist/sdk/lifecycle/create.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/lifecycle/create
- *
- * Implements the pm create command surface and its agent-facing runtime behavior.
- */
 import { type ResolvedItemTypeDefinition, type RuntimeFieldRegistry, type GlobalOptions } from "../runtime-primitives.js";
 import { type SimilarityAdvisory } from "../similarity.js";
 import { type LifecycleTransitionSuggestion } from "./lifecycle-transitions.js";

package/dist/sdk/lifecycle/create.js

@@ -4,12 +4,16 @@
  * Implements the pm create 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]="7d69bb56-9fab-5059-9357-5b6bea2078b9")}catch(e){}}();
-import { pathExists, removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, resolvePriority, getFocusedItem, normalizeStatusInput, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, acquireLock, printError, buildInvalidTypeError, resolveTypeSynonym, collectRuntimeCreateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, PmCliError, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, listAllItemMetadataLight, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+!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]="4dff80ab-acfc-5f81-a546-3f19629d97be")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, resolvePriority, getFocusedItem, normalizeStatusInput, isTerminalStatus, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, acquireLock, printError, buildInvalidTypeError, resolveTypeSynonym, collectRuntimeCreateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, PmCliError, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, listAllItemMetadataLight, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { requireTerminalReasonWithRecovery } from "../lifecycle-policy.js";
 import { evaluateSimilarityGovernance, similarityAdvisoryWarnings, } from "../similarity.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
 import { collectNewOrderingCycleWarnings } from "../graph/mutation-advisory.js";
+import { assertHierarchyMutationAllowed } from "../graph/hierarchy-integrity.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { acquireHierarchyMutationLock } from "./hierarchy-mutation-lock.js";
 import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parseRegressionInput, } from "./metadata-normalizers.js";
 import { applyLegacyNoneCollectionNormalizers, createLegacyNoneCollectionNormalizers, assertNoLegacyNoneToken, assertNoLegacyNoneTokens, isLegacyNoneToken, } from "./legacy-none-tokens.js";
 import { suggestNextLifecycleTransition, } from "./lifecycle-transitions.js";
@@ -837,12 +841,7 @@ async function loadCreateTemplateOptionsFromRuntime(templateName, global, pmRoot
     return readTemplateOptionsFromRuntimeResult(handlerResult.result, templateName);
 }
 function ensureInitHasRun(pmRoot) {
-    return pathExists(getSettingsPath(pmRoot)).then((exists) => {
-        /* c8 ignore next -- init guard failures are covered by top-level create command tests. */
-        if (!exists) {
-            throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-        }
-    });
+    return assertInitializedTracker(pmRoot);
 }
 /**
  * Resolve an optional string item-metadata field for {@link runCreate}: yields
@@ -1444,114 +1443,140 @@ async function writeCreatedItem(params) {
     const { pmRoot, type, id, settings, typeRegistry, author, extensionFieldNames, afterDocument, beforeDocument, historyMessage, changedFields, nowValue, similarityCandidate, allowDuplicate, } = params;
     const itemPath = getItemPath(pmRoot, type, id, settings.item_format, typeRegistry.type_to_folder);
     const historyPath = getHistoryPath(pmRoot, id);
-    const lockRelease = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
+    const relationshipRegistry = resolveWorkspaceRelationshipKindRegistry();
+    const hierarchyMutationRequired = afterDocument.metadata.parent !== undefined ||
+        (afterDocument.metadata.dependencies ?? []).some((dependency) => relationshipRegistry.resolve(dependency.kind)?.hierarchy);
+    const hierarchyLockRelease = await acquireHierarchyMutationLock({
+        pmRoot,
+        author,
+        ttlSeconds: settings.locks.ttl_seconds,
+        waitMs: settings.locks.wait_ms,
+        required: hierarchyMutationRequired,
+    });
+    let hierarchyLockHeld = hierarchyMutationRequired;
     let hookWarnings = [];
     try {
-        const graphBeforeCreate = afterDocument.metadata.dependencies &&
-            afterDocument.metadata.dependencies.length > 0
-            ? await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)
-            : undefined;
-        const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
-        if (existing) {
-            throw new PmCliError(`Item "${id}" already exists`, EXIT_CODE.CONFLICT);
-        }
-        await runActiveBeforeMutationHooks({
-            pm_root: pmRoot,
-            operation: "create",
-            before: null,
-            after: afterDocument,
-            changed_fields: changedFields,
-            sdk: createMutationGuardSdk({
-                pmRoot,
-                settings,
-                typeToFolder: typeRegistry.type_to_folder,
-            }),
-        });
-        const releaseDerivedIndexLock = await acquireItemMetadataDerivedIndexLock(pmRoot, author, {
-            required: settings.governance.duplicate_detection_mode === "strict" &&
-                allowDuplicate !== true,
-        });
-        let derivedIndexWarnings = [];
+        const lockRelease = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
         try {
-            if (settings.governance.duplicate_detection_mode === "strict" &&
-                allowDuplicate !== true) {
-                await evaluateSimilarityGovernance(similarityCandidate, {
+            const graphBeforeCreate = afterDocument.metadata.parent !== undefined ||
+                (afterDocument.metadata.dependencies !== undefined &&
+                    afterDocument.metadata.dependencies.length > 0)
+                ? await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)
+                : undefined;
+            const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
+            if (existing) {
+                throw new PmCliError(`Item "${id}" already exists`, EXIT_CODE.CONFLICT);
+            }
+            if (graphBeforeCreate) {
+                const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+                assertHierarchyMutationAllowed(graphBeforeCreate, [...graphBeforeCreate, afterDocument.metadata], id, (status) => isTerminalStatus(status, statusRegistry), relationshipRegistry);
+            }
+            await runActiveBeforeMutationHooks({
+                pm_root: pmRoot,
+                operation: "create",
+                before: null,
+                after: afterDocument,
+                changed_fields: changedFields,
+                sdk: createMutationGuardSdk({
                     pmRoot,
-                    mode: "strict",
-                    threshold: settings.governance.duplicate_detection_threshold,
-                    limit: settings.governance.duplicate_detection_limit,
-                    allowDuplicate: false,
+                    settings,
+                    typeToFolder: typeRegistry.type_to_folder,
+                }),
+            });
+            const releaseDerivedIndexLock = await acquireItemMetadataDerivedIndexLock(pmRoot, author, {
+                required: settings.governance.duplicate_detection_mode === "strict" &&
+                    allowDuplicate !== true,
+            });
+            let derivedIndexWarnings = [];
+            try {
+                if (settings.governance.duplicate_detection_mode === "strict" &&
+                    allowDuplicate !== true) {
+                    await evaluateSimilarityGovernance(similarityCandidate, {
+                        pmRoot,
+                        mode: "strict",
+                        threshold: settings.governance.duplicate_detection_threshold,
+                        limit: settings.governance.duplicate_detection_limit,
+                        allowDuplicate: false,
+                    });
+                }
+                await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, {
+                    format: settings.item_format,
+                    schema: settings.schema,
+                    extensionFieldNames,
+                }));
+                try {
+                    const entry = createHistoryEntry({
+                        nowIso: nowValue,
+                        author,
+                        op: "create",
+                        before: beforeDocument,
+                        after: afterDocument,
+                        message: historyMessage,
+                    });
+                    await appendHistoryEntry(historyPath, entry);
+                }
+                catch (error) {
+                    await removeFileIfExists(itemPath);
+                    throw error;
+                }
+                if (hierarchyLockHeld) {
+                    await hierarchyLockRelease();
+                    hierarchyLockHeld = false;
+                }
+                derivedIndexWarnings = await refreshItemMetadataDerivedIndex({
+                    pmRoot,
+                    preferredFormat: settings.item_format,
+                    typeToFolder: typeRegistry.type_to_folder,
+                    schema: settings.schema,
+                    itemPath,
+                    document: afterDocument,
                 });
             }
-            await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, {
-                format: settings.item_format,
-                schema: settings.schema,
-                extensionFieldNames,
-            }));
-            try {
-                const entry = createHistoryEntry({
-                    nowIso: nowValue,
-                    author,
+            finally {
+                await releaseDerivedIndexLock();
+            }
+            hookWarnings = [
+                ...(graphBeforeCreate
+                    ? collectNewOrderingCycleWarnings(graphBeforeCreate, [...graphBeforeCreate, afterDocument.metadata], id)
+                    : []),
+                ...derivedIndexWarnings,
+                ...(await runActiveOnWriteHooks({
+                    path: itemPath,
+                    scope: "project",
                     op: "create",
+                    item_id: afterDocument.metadata.id,
+                    item_type: afterDocument.metadata.type,
                     before: beforeDocument,
                     after: afterDocument,
-                    message: historyMessage,
-                });
-                await appendHistoryEntry(historyPath, entry);
-            }
-            catch (error) {
-                await removeFileIfExists(itemPath);
-                throw error;
-            }
-            derivedIndexWarnings = await refreshItemMetadataDerivedIndex({
-                pmRoot,
-                preferredFormat: settings.item_format,
-                typeToFolder: typeRegistry.type_to_folder,
-                schema: settings.schema,
-                itemPath,
-                document: afterDocument,
+                    changed_fields: changedFields,
+                })),
+                ...(await runActiveOnWriteHooks({
+                    path: historyPath,
+                    scope: "project",
+                    op: "create:history",
+                    item_id: afterDocument.metadata.id,
+                    item_type: afterDocument.metadata.type,
+                    before: beforeDocument,
+                    after: afterDocument,
+                    changed_fields: changedFields,
+                })),
+            ];
+            recordAfterCommandAffectedItem({
+                id: afterDocument.metadata.id,
+                op: "create",
+                item_type: afterDocument.metadata.type,
+                status: afterDocument.metadata.status,
+                current: projectAfterCommandItemSnapshot(afterDocument.metadata, changedFields),
+                changed_fields: changedFields,
             });
         }
         finally {
-            await releaseDerivedIndexLock();
+            await lockRelease();
         }
-        hookWarnings = [
-            ...(graphBeforeCreate
-                ? collectNewOrderingCycleWarnings(graphBeforeCreate, [...graphBeforeCreate, afterDocument.metadata], id)
-                : []),
-            ...derivedIndexWarnings,
-            ...(await runActiveOnWriteHooks({
-                path: itemPath,
-                scope: "project",
-                op: "create",
-                item_id: afterDocument.metadata.id,
-                item_type: afterDocument.metadata.type,
-                before: beforeDocument,
-                after: afterDocument,
-                changed_fields: changedFields,
-            })),
-            ...(await runActiveOnWriteHooks({
-                path: historyPath,
-                scope: "project",
-                op: "create:history",
-                item_id: afterDocument.metadata.id,
-                item_type: afterDocument.metadata.type,
-                before: beforeDocument,
-                after: afterDocument,
-                changed_fields: changedFields,
-            })),
-        ];
-        recordAfterCommandAffectedItem({
-            id: afterDocument.metadata.id,
-            op: "create",
-            item_type: afterDocument.metadata.type,
-            status: afterDocument.metadata.status,
-            current: projectAfterCommandItemSnapshot(afterDocument.metadata, changedFields),
-            changed_fields: changedFields,
-        });
     }
     finally {
-        await lockRelease();
+        if (hierarchyLockHeld)
+            await hierarchyLockRelease();
     }
     return hookWarnings;
 }
@@ -1890,4 +1915,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=7d69bb56-9fab-5059-9357-5b6bea2078b9
+//# debugId=4dff80ab-acfc-5f81-a546-3f19629d97be

package/dist/sdk/lifecycle/delete.js

@@ -4,15 +4,14 @@
  * Implements the SDK-owned delete lifecycle operation shared by every surface.
  */
 
-!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]="14aa55e1-cb5f-55ea-bf4c-412217d87449")}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]="7819b53c-b0e4-50b0-a670-f80b36765085")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import path from "node:path";
-import { pathExists, EXIT_CODE, PmCliError, toItemRecord, deleteItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { toItemRecord, deleteItem, getHistoryPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 /** Implements run delete for the public runtime surface of this module. */
 export async function runDelete(id, options, 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 settings = await readSettings(pmRoot);
     const author = resolveAuthor(options.author, settings.author_default);
     const result = await deleteItem({
@@ -44,4 +43,4 @@ export async function runDelete(id, options, global) {
     };
 }
 //# sourceMappingURL=delete.js.map
-//# debugId=14aa55e1-cb5f-55ea-bf4c-412217d87449
+//# debugId=7819b53c-b0e4-50b0-a670-f80b36765085

package/dist/sdk/lifecycle/focus.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/lifecycle/focus
- *
- * Implements the SDK-owned focus lifecycle operation shared by every surface.
- */
 import { type GlobalOptions } from "../runtime-primitives.js";
 /** Documents the focus options payload exchanged by command, SDK, and package integrations. */
 export interface FocusOptions {

package/dist/sdk/lifecycle/focus.js

@@ -4,13 +4,12 @@
  * Implements the SDK-owned focus lifecycle operation shared by every surface.
  */
 
-!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]="0f43df79-0b27-53b3-b8bd-9f2a35561733")}catch(e){}}();
-import { pathExists, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, EXIT_CODE, PmCliError, clearFocusedItem, getFocusedItem, setFocusedItem, buildItemNotFoundError, locateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
+!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]="a5ddb139-9780-50e0-87a5-621913cb0de4")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, EXIT_CODE, PmCliError, clearFocusedItem, getFocusedItem, setFocusedItem, buildItemNotFoundError, locateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
 import { recordFocusSemanticAttribution } from "../context/semantic-session-attribution.js";
 async function ensureInitialized(pmRoot) {
-    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);
 }
 /** Implements run focus for the public runtime surface of this module. */
 export async function runFocus(id, options, global) {
@@ -90,4 +89,4 @@ function nonEmptyTitleOrNull(title) {
     return title.trim().length > 0 ? title : null;
 }
 //# sourceMappingURL=focus.js.map
-//# debugId=0f43df79-0b27-53b3-b8bd-9f2a35561733
+//# debugId=a5ddb139-9780-50e0-87a5-621913cb0de4