@unbrained/pm-cli 2026.8.21 → 2026.8.22

package/dist/sdk/lifecycle/create.js

@@ -4,13 +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]="a10348fe-746d-5dc7-8cd4-30453c602a3f")}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]="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, 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 { 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";
@@ -1440,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;
 }
@@ -1886,4 +1915,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=a10348fe-746d-5dc7-8cd4-30453c602a3f
+//# debugId=4dff80ab-acfc-5f81-a546-3f19629d97be

package/dist/sdk/lifecycle/hierarchy-mutation-lock.d.ts

@@ -0,0 +1,15 @@
+/** Inputs for the internal workspace-wide hierarchy mutation lock. */
+export interface HierarchyMutationLockOptions {
+    /** Tracker root whose hierarchy is being changed. */
+    pmRoot: string;
+    /** Principal recorded as the lock owner. */
+    author: string;
+    /** Tracker-configured stale-lock lifetime. */
+    ttlSeconds: number;
+    /** Tracker-configured bounded lock wait. */
+    waitMs: number;
+    /** Whether this mutation can add hierarchy evidence. */
+    required: boolean;
+}
+/** Acquire the shared hierarchy writer lock, or return a no-op release. */
+export declare function acquireHierarchyMutationLock(options: HierarchyMutationLockOptions): Promise<() => Promise<void>>;

package/dist/sdk/lifecycle/hierarchy-mutation-lock.js

@@ -0,0 +1,25 @@
+/**
+ * @module sdk/lifecycle/hierarchy-mutation-lock
+ *
+ * Serializes hierarchy-affecting create and update transactions so each
+ * before/after integrity decision is made from a fresh workspace snapshot.
+ */
+
+!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]="39a36d42-29b1-5f0f-a8b2-f3bfc0ef78c2")}catch(e){}}();
+import { acquireLock } from "../../core/lock/lock.js";
+const HIERARCHY_MUTATION_LOCK_ID = "hierarchy-integrity";
+/** Acquire the shared hierarchy writer lock, or return a no-op release. */
+export async function acquireHierarchyMutationLock(options) {
+    const release = options.required
+        ? await acquireLock(options.pmRoot, HIERARCHY_MUTATION_LOCK_ID, options.ttlSeconds, options.author, false, false, options.waitMs)
+        : async () => { };
+    let released = false;
+    return async () => {
+        if (released)
+            return;
+        released = true;
+        await release();
+    };
+}
+//# sourceMappingURL=hierarchy-mutation-lock.js.map
+//# debugId=39a36d42-29b1-5f0f-a8b2-f3bfc0ef78c2

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

@@ -121,6 +121,8 @@ interface DependencyRemovalSelector {
     id: string;
     kind?: (typeof DEPENDENCY_KIND_VALUES)[number];
     source_kind?: string;
+    author?: string;
+    created_at?: string;
 }
 /** Parse dependency additions into their canonical storage representation. */
 export declare function parseDependencyAdditions(raw: string[] | undefined, prefix: string, nowIso: string, fallbackAuthor: string): ParsedDependencyUpdates;