@unbrained/pm-cli 2026.8.27 → 2026.8.29

package/dist/sdk/graph/assembly.js

@@ -1,7 +1,7 @@
 
-!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]="9a6974b3-63d7-5dc7-8329-0f15f0dc83ec")}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]="e04a91fa-4625-50fd-9bfd-c712126baf0d")}catch(e){}}();
 import { RelationshipGraph, } from "../relationships.js";
-import { isExternalDependencySourceKind } from "../dependency-provenance.js";
+import { isExternalDependencyReference, isExternalDependencySourceKind, } from "../dependency-provenance.js";
 import { analyzeHierarchyIntegrity, } from "./hierarchy-integrity.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
 export { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
@@ -22,6 +22,25 @@ export function normalizeDependencyGraphTarget(target) {
         ? undefined
         : normalized;
 }
+/** Return whether edge provenance assigns a normalized target to the external graph namespace. */
+function isExternalGraphReference(target, sourceKind, externalAllowed = true) {
+    const normalized = normalizeDependencyReferenceTarget(target);
+    return (externalAllowed &&
+        (isExternalDependencySourceKind(sourceKind) ||
+            (normalized !== undefined && isExternalDependencyReference(normalized))));
+}
+/** Build a namespace-aware reference identity: local ids are case-folded while external locators retain case. */
+function dependencyReferenceIdentityKey(target, sourceKind) {
+    return isExternalGraphReference(target, sourceKind)
+        ? `external\u0000${target}`
+        : `local\u0000${target.toLowerCase()}`;
+}
+/** Resolve one normalized edge target through the namespace selected by its provenance. */
+function resolveGraphReferenceTarget(target, sourceKind, canonicalIds, externalGraphIds) {
+    return isExternalGraphReference(target, sourceKind)
+        ? externalGraphIds.get(target)
+        : canonicalIds.get(target.toLowerCase());
+}
 /** Compare text case-insensitively with an exact-spelling deterministic tie-breaker. */
 function compareCaseFoldedText(left, right) {
     const normalizedLeft = left.toLowerCase();
@@ -45,7 +64,7 @@ function countDependencyRowIdentities(item) {
         const kind = typeof legacyDependency.kind === "string"
             ? legacyDependency.kind
             : "related";
-        const key = `${kind}\u0000${target.toLowerCase()}`;
+        const key = `${kind}\u0000${dependencyReferenceIdentityKey(target, legacyDependency.source_kind)}`;
         const existing = occurrences.get(key);
         if (existing)
             existing.count += 1;
@@ -94,7 +113,9 @@ function decodeOrderingStorageContradiction(item, blocker, dependency, isTermina
     if (typeof dependency !== "object" || dependency === null)
         return undefined;
     const target = normalizeDependencyReferenceTarget(dependency.id);
-    if (!target || target.toLowerCase() !== blocker.toLowerCase())
+    if (!target ||
+        dependencyReferenceIdentityKey(target, dependency.source_kind) !==
+            dependencyReferenceIdentityKey(blocker))
         return undefined;
     const definition = registry.resolve(typeof dependency.kind === "string" ? dependency.kind : "related");
     if (definition?.ordering !== true ||
@@ -151,9 +172,11 @@ export function collectDanglingDependencyReferences(items, isTerminal = (status)
     const safeItems = items.filter((item) => typeof item?.id === "string" && item.id.trim().length > 0);
     const knownIds = new Set(safeItems.map((item) => item.id.trim().toLowerCase()));
     const rows = new Map();
-    const addReference = (item, target, kind, source) => {
+    const addReference = (item, target, kind, source, externalAllowed) => {
         const normalized = normalizeDependencyReferenceTarget(target);
-        if (!normalized || knownIds.has(normalized.toLowerCase())) {
+        if (!normalized ||
+            knownIds.has(normalized.toLowerCase()) ||
+            isExternalGraphReference(normalized, undefined, externalAllowed)) {
             return;
         }
         const row = {
@@ -168,8 +191,8 @@ export function collectDanglingDependencyReferences(items, isTerminal = (status)
         rows.set(`${row.holder_id}::${row.target_id}::${row.kind}::${row.source}`, row);
     };
     for (const item of safeItems) {
-        addReference(item, item.parent, "parent", "parent");
-        addReference(item, item.blocked_by, "blocked_by", "blocked_by");
+        addReference(item, item.parent, "parent", "parent", false);
+        addReference(item, item.blocked_by, "blocked_by", "blocked_by", true);
         for (const dependency of item.dependencies ?? []) {
             // Public SDK callers may supply legacy or JSON-decoded payloads that do
             // not yet satisfy the current structured dependency contract.
@@ -182,7 +205,7 @@ export function collectDanglingDependencyReferences(items, isTerminal = (status)
             }
             addReference(item, legacyDependency.id, typeof legacyDependency.kind === "string"
                 ? legacyDependency.kind
-                : "related", "dependency");
+                : "related", "dependency", true);
         }
     }
     const sorted = [...rows.values()].sort((left, right) => left.holder_id.localeCompare(right.holder_id) ||
@@ -213,15 +236,21 @@ export function collectMissingDependencyTargetIds(dangling) {
 export function collectExternalDependencyTargetIds(items) {
     const targets = new Map();
     for (const item of items) {
+        const scalarBlocker = normalizeDependencyGraphTarget(item.blocked_by);
+        if (scalarBlocker &&
+            isExternalGraphReference(scalarBlocker) &&
+            !targets.has(scalarBlocker)) {
+            targets.set(scalarBlocker, scalarBlocker);
+        }
         for (const dependency of item.dependencies ?? []) {
             if (typeof dependency !== "object" ||
                 dependency === null ||
-                !isExternalDependencySourceKind(dependency.source_kind)) {
+                !isExternalGraphReference(dependency.id, dependency.source_kind)) {
                 continue;
             }
-            const id = normalizeDependencyReferenceTarget(dependency.id);
-            if (id && !targets.has(id.toLowerCase())) {
-                targets.set(id.toLowerCase(), id);
+            const id = normalizeDependencyGraphTarget(dependency.id);
+            if (id && !targets.has(id)) {
+                targets.set(id, id);
             }
         }
     }
@@ -230,7 +259,7 @@ export function collectExternalDependencyTargetIds(items) {
 const hierarchyIntegrityByAssembly = new WeakMap();
 /** Read the hierarchy analysis paired with an assembly created by this module. */
 export function getWorkspaceHierarchyIntegrity(assembly) {
-    return assembly.hierarchyIntegrity ?? hierarchyIntegrityByAssembly.get(assembly);
+    return (assembly.hierarchyIntegrity ?? hierarchyIntegrityByAssembly.get(assembly));
 }
 /** Count raw dependency rows that use a registered compatibility alias instead of its canonical kind. */
 export function collectLegacyDependencyAliasCounts(items, registry = resolveWorkspaceRelationshipKindRegistry()) {
@@ -274,7 +303,7 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
         while (usedGraphIds.has(graphId.toLowerCase())) {
             graphId = `external:${graphId}`;
         }
-        externalGraphIds.set(id.toLowerCase(), graphId);
+        externalGraphIds.set(id, graphId);
         usedGraphIds.add(graphId.toLowerCase());
     }
     const graphItems = safeItems.map((item) => {
@@ -287,9 +316,7 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
             const target = normalizeDependencyGraphTarget(dependency.id);
             if (!target)
                 return [];
-            const targetId = isExternalDependencySourceKind(dependency.source_kind)
-                ? externalGraphIds.get(target.toLowerCase())
-                : canonicalIds.get(target.toLowerCase());
+            const targetId = resolveGraphReferenceTarget(target, dependency.source_kind, canonicalIds, externalGraphIds);
             return [
                 {
                     id: targetId,
@@ -301,7 +328,9 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
             id: item.id.trim(),
             ...(parent ? { parent: canonicalIds.get(parent.toLowerCase()) } : {}),
             ...(blocker
-                ? { blocked_by: canonicalIds.get(blocker.toLowerCase()) }
+                ? {
+                    blocked_by: resolveGraphReferenceTarget(blocker, undefined, canonicalIds, externalGraphIds),
+                }
                 : {}),
             dependencies,
         };
@@ -312,7 +341,7 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
             ...graphItems,
             ...missingIds.map((id) => ({ id })),
             ...externalIds.map((id) => ({
-                id: externalGraphIds.get(id.toLowerCase()),
+                id: externalGraphIds.get(id),
             })),
         ], relationshipRegistry),
         details: [
@@ -330,7 +359,7 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
                 status: "missing",
             })),
             ...externalIds.map((id) => ({
-                id: externalGraphIds.get(id.toLowerCase()),
+                id: externalGraphIds.get(id),
                 title: `[external] ${id}`,
                 status: "external",
             })),
@@ -346,4 +375,4 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
     return assembly;
 }
 //# sourceMappingURL=assembly.js.map
-//# debugId=9a6974b3-63d7-5dc7-8329-0f15f0dc83ec
+//# debugId=e04a91fa-4625-50fd-9bfd-c712126baf0d

package/dist/sdk/history-repair.d.ts

@@ -83,7 +83,7 @@ export interface MergeReceiptProofResult {
     /** Whether exact receipt identity, path, field, and value-hash evidence proves the snapshot. */
     trusted: boolean;
     /** Stable explanation for the trust decision. */
-    reason: "trusted_clone_local_driver_evidence" | "git_workspace_unavailable" | "item_path_unavailable" | "no_item_receipts" | "no_receipt_set_proves_snapshot";
+    reason: "trusted_merge_driver_hash_evidence" | "git_workspace_unavailable" | "item_path_unavailable" | "no_item_receipts" | "no_receipt_set_proves_snapshot";
     /** Exact receipt identities accepted as proof; empty when proof is refused. */
     receipt_ids: string[];
 }

package/dist/sdk/history-repair.js

@@ -4,7 +4,7 @@
  * Implements the pm history repair 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]="7a21ee76-ed53-57a0-9776-c787297ed7b6")}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]="04dbdc08-ad98-543f-96dc-fde635bae92e")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -27,7 +27,7 @@ import { listAllItemMetadataWithBody, readLocatedItem, } from "../core/store/ite
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { resolveHistorySubject } from "./history-redact.js";
-import { summarizeMergeReceipt, } from "./merge/receipts.js";
+import { inspectMergeReceiptEvidence, summarizeMergeReceipt, } from "./merge/receipts.js";
 import { listInvalidProvenanceHistoryStreamIds, normalizeInvalidHistoryProvenance, } from "./governance/provenance-health.js";
 function replayFieldValue(document, field) {
     return field === "body"
@@ -148,8 +148,6 @@ async function canonicalRealPath(value) {
     }
 }
 async function verifyReceiptAgainstSnapshot(params) {
-    if (params.receipt.evidence_source !== "clone_local")
-        return null;
     const receiptPath = await canonicalRealPath(path.resolve(params.gitWorkspaceRoot, params.receipt.item_path));
     if (receiptPath !== params.currentPath)
         return null;
@@ -159,11 +157,11 @@ async function verifyReceiptAgainstSnapshot(params) {
             ...params.receipt.union_fields,
             ...params.receipt.decisions.map((decision) => decision.field),
         ]),
-    ].sort((left, right) => left.localeCompare(right));
+    ].sort();
     const hashes = params.receipt.merged_field_hashes;
     if (!hashes || declaredFields.length === 0)
         return null;
-    const hashFields = Object.keys(hashes).sort((left, right) => left.localeCompare(right));
+    const hashFields = Object.keys(hashes).sort();
     if (declaredFields.length !== hashFields.length ||
         declaredFields.some((field, index) => field !== hashFields[index])) {
         return null;
@@ -214,7 +212,7 @@ async function verifyMergeReceiptProof(params) {
                 reconciliationFields.every((field) => trustedFields.has(field))))) {
         return {
             trusted: true,
-            reason: "trusted_clone_local_driver_evidence",
+            reason: "trusted_merge_driver_hash_evidence",
             receipt_ids: trustedReceipts.map(({ receipt }) => receipt.id),
         };
     }
@@ -225,7 +223,18 @@ async function verifyMergeReceiptProof(params) {
     };
 }
 async function resolveHistoryRepairMergeEvidence(params) {
-    const subjectMergeReceipts = params.options.mergeReceiptProof?.receipts.filter((receipt) => receipt.item_id === params.subjectId) ?? [];
+    const requestedReceiptIds = new Set(params.options.mergeReceiptProof?.receipts
+        .filter((receipt) => receipt.item_id === params.subjectId)
+        .map((receipt) => receipt.id) ?? []);
+    const authoritativeReceiptEvidence = params.options.mergeReceiptProof
+        ? await inspectMergeReceiptEvidence(params.options.mergeReceiptProof.gitWorkspaceRoot ?? process.cwd(), {
+            includeReconciled: true,
+            includeLossless: true,
+            pmRoot: params.pmRoot,
+        })
+        : undefined;
+    const subjectMergeReceipts = authoritativeReceiptEvidence?.receipts.filter((receipt) => receipt.item_id === params.subjectId &&
+        requestedReceiptIds.has(receipt.id)) ?? [];
     const mergeReceiptProof = params.options.mergeReceiptProof
         ? await verifyMergeReceiptProof({
             proof: {
@@ -244,7 +253,7 @@ async function resolveHistoryRepairMergeEvidence(params) {
         params.options.force !== true) {
         throw new PmCliError(`Merge receipt evidence for ${params.subjectId} does not prove the exact item snapshot (${mergeReceiptProof.reason}).`, EXIT_CODE.CONFLICT, {
             code: "merge_reconcile_receipt_evidence_untrusted",
-            required: "Use clone-local driver evidence whose canonical path, declared fields, and merged-value hashes match the current item, or review the mismatch and rerun with --force.",
+            required: "Use authoritative clone-local or durable receipt evidence whose canonical path, declared fields, and merged-value hashes match the current item, or review the mismatch and rerun with --force.",
             recovery: { suggested_retry: "pm merge reconcile --dry-run" },
         });
     }
@@ -405,6 +414,7 @@ export async function runHistoryRepair(id, options, global) {
         : undefined;
     const { mergeReceiptProof, effectiveAuditContext } = await resolveHistoryRepairMergeEvidence({
         options,
+        pmRoot,
         subjectId: subject.id,
         itemReplayContext,
         reconciliation,
@@ -581,4 +591,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=7a21ee76-ed53-57a0-9776-c787297ed7b6
+//# debugId=04dbdc08-ad98-543f-96dc-fde635bae92e

package/dist/sdk/index.d.ts

@@ -118,6 +118,7 @@ export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="ae931d1f-b7c6-5f15-aa9a-cda07f375b74")}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]="ea1845ab-34f5-5a1c-ad49-ac81495c1840")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./mcp/protocol.js";
 export * from "./mcp/interactions.js";
@@ -115,6 +115,7 @@ export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
 export * from "./output-contracts.js";
+export * from "./agent/task-transcript-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";
@@ -175,4 +176,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=ae931d1f-b7c6-5f15-aa9a-cda07f375b74
+//# debugId=ea1845ab-34f5-5a1c-ad49-ac81495c1840

package/dist/sdk/learnings.d.ts

@@ -22,6 +22,8 @@ export interface LearningsCommandOptions {
     limit?: string;
     /** Return complete learning history after a mutation instead of a bounded receipt. */
     fullHistory?: boolean;
+    /** Append only when no learning has the same resolved author and text. */
+    ifAbsent?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -49,6 +51,8 @@ export interface LearningsResult {
     mutation_receipt?: AnnotationMutationReceipt;
     /** Declares whether older learnings were withheld from a mutation response. */
     omission_receipt?: AnnotationOmissionReceipt;
+    /** Whether a requested mutation changed persisted state. */
+    changed?: boolean;
 }
 /** Implements run learnings for the public runtime surface of this module. */
 export declare function runLearnings(id: string, options: LearningsCommandOptions, global: GlobalOptions): Promise<LearningsResult>;

package/dist/sdk/learnings.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]="93184f29-f215-5413-9628-fb5b34523995")}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]="972816c9-b407-5b89-a744-249c9771451f")}catch(e){}}();
 import { parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 /** Implements run learnings for the public runtime surface of this module. */
 export async function runLearnings(id, options, global) {
@@ -11,11 +11,14 @@ export async function runLearnings(id, options, global) {
         deleteOp: "learning_delete",
         parseText: (raw) => parseAnnotationTextInput(raw),
         createEntry: (entry) => entry,
-        bypassOwnershipConflict: Boolean(options.edit === undefined && options.delete === undefined &&
+        bypassOwnershipConflict: Boolean(options.edit === undefined &&
+            options.delete === undefined &&
             options.ownershipAppendBypass),
         conflictGuidance: {
             required: "For an approved append-only handoff on another owner's item, use the package-provided ownership bypass before considering --force.",
-            examples: ['pm learnings pm-a1b2 --add "review learning" --author "reviewer" --force'],
+            examples: [
+                'pm learnings pm-a1b2 --add "review learning" --author "reviewer" --force',
+            ],
             nextSteps: [
                 "Use an installed package's narrow append-only ownership bypass when available.",
                 "Use --force only when an ownership override is explicitly approved.",
@@ -24,4 +27,4 @@ export async function runLearnings(id, options, global) {
     });
 }
 //# sourceMappingURL=learnings.js.map
-//# debugId=93184f29-f215-5413-9628-fb5b34523995
+//# debugId=972816c9-b407-5b89-a744-249c9771451f

package/dist/sdk/lifecycle/close.js

@@ -4,11 +4,12 @@
  * 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]="781b5118-7b07-53c7-802f-c889cb797a96")}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]="9f28f7d8-993b-5201-b606-d1eab0c3ff5c")}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 { nowIso } from "../../core/shared/time.js";
 import { renderPmCommand } from "../command-line.js";
 const CLOSE_VALIDATION_FIELDS = [
     { key: "resolution", label: "resolution (--resolution)" },
@@ -415,7 +416,7 @@ export async function closeItem(id, closeReasonText, options, global) {
     // informational note instead of the warn/strict validation warning.
     const trackerItems = await listAllItemMetadataLight(pmRoot, settings.item_format, typeToFolder, undefined, settings.schema);
     const activeChildIds = findActiveChildIds(trackerItems, located.id, statusRegistry);
-    const closedAt = new Date().toISOString();
+    const closedAt = nowIso();
     const completedAt = options.completedAt === undefined
         ? closedAt
         : resolveIsoOrRelative(options.completedAt, new Date(closedAt), "completed-at");
@@ -457,4 +458,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=781b5118-7b07-53c7-802f-c889cb797a96
+//# debugId=9f28f7d8-993b-5201-b606-d1eab0c3ff5c

package/dist/sdk/lifecycle/create.js

@@ -4,9 +4,9 @@
  * 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]="02c41ea1-8d4e-5239-b95a-a07210b63d7f")}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]="c9bfbfd4-3d34-5fa7-b264-6bf9ed5f7f81")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
-import { resolveMutationStdinTokenFields } from "../../core/item/parse.js";
+import { assertNoAmbiguousBareCommaEntry, looksLikeStructuredKeyValueEntry, resolveMutationStdinTokenFields, } from "../../core/item/parse.js";
 import { removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, shouldResolveMutationStdinTokens, transferMutationStdinTokenPolicy, 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";
@@ -19,7 +19,7 @@ import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parse
 import { applyLegacyNoneCollectionNormalizers, createLegacyNoneCollectionNormalizers, assertNoLegacyNoneToken, assertNoLegacyNoneTokens, isLegacyNoneToken, } from "./legacy-none-tokens.js";
 import { suggestNextLifecycleTransition, } from "./lifecycle-transitions.js";
 import { parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, parseLinkedTestBoolean, parseLinkedTestContextMode, parseLinkedTestEnvClear, parseLinkedTestEnvSet, parseLinkedTestMinLines, parseLinkedTestRegexList, parseLinkedTestStringList, parseLinkedTestWorkspaceContextMode, } from "../test/parsers.js";
-import { looksLikeStructuredLinkedTestEntry, normalizeStructuredLinkedTestEntry, } from "../test/entry.js";
+import { STRUCTURED_LINKED_TEST_KEYS, normalizeStructuredLinkedTestEntry, } from "../test/entry.js";
 import { attachLinkedTestMutationProvenance } from "../test/trust.js";
 import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR, parseCommandUnsetTargets, resolveRuntimeUnsetFieldDefinition, } from "./shared-unset-fields.js";
 import { ensureEnumValue } from "./recurrence-parsers.js";
@@ -202,13 +202,7 @@ function normalizeDependencyKindInput(raw) {
         : raw;
 }
 function looksLikeStructuredEntry(raw, keys) {
-    if (raw.startsWith("```") || raw.includes("\n")) {
-        return true;
-    }
-    const keyPattern = keys
-        .map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
-        .join("|");
-    if (new RegExp(`^(?:[-*+]\\s+)?(?:${keyPattern})\\s*[:=]`, "i").test(raw)) {
+    if (looksLikeStructuredKeyValueEntry(raw, keys)) {
         return true;
     }
     // A first-key typo (e.g. `bogus=v,id=pm-2`) must still be parsed so the unknown
@@ -281,6 +275,7 @@ export function parseFiles(raw) {
     const values = raw.map((entry) => {
         const trimmedEntry = entry.trim();
         const isStructured = looksLikeStructuredEntry(trimmedEntry, LINKED_ARTIFACT_SEED_KEYS);
+        assertNoAmbiguousBareCommaEntry(trimmedEntry, "--file", "file path", isStructured);
         const kv = isStructured
             ? parseCsvKv(entry, "--file")
             : { path: trimmedEntry };
@@ -305,7 +300,9 @@ export function parseTests(raw) {
     assertNoLegacyNoneTokens(raw, "--test", "Use --clear-tests to clear linked tests.");
     const values = raw.map((entry) => {
         const trimmedEntry = entry.trim();
-        const kv = looksLikeStructuredLinkedTestEntry(trimmedEntry)
+        const isStructured = looksLikeStructuredEntry(trimmedEntry, STRUCTURED_LINKED_TEST_KEYS);
+        assertNoAmbiguousBareCommaEntry(trimmedEntry, "--test", "test command", isStructured);
+        const kv = isStructured
             ? normalizeStructuredLinkedTestEntry(parseCsvKv(entry, "--test"), "--test")
             : { command: trimmedEntry };
         const command = parseOptionalString(kv.command);
@@ -1331,6 +1328,19 @@ function assertNoCreateFieldUnsetConflicts(registeredItemFieldValues, runtimeCre
     }
 }
 /** Throw the aggregated `missing_required_option` error when a type's required create options and/or required type-option keys were not all supplied in one invocation. Builds a type-aware valid example and staged-onboarding next steps (a strict-mode invocation also carries a compact recovery envelope). A no-op when nothing is missing. */
+/** Truthful empty-collection alternatives for strict required create fields. */
+const CLEAR_FLAG_BY_REQUIRED_CREATE_FLAG = {
+    "--comment": "--clear-comments",
+    "--dep": "--clear-deps",
+    "--doc": "--clear-docs",
+    "--event": "--clear-events",
+    "--file": "--clear-files",
+    "--learning": "--clear-learnings",
+    "--note": "--clear-notes",
+    "--reminder": "--clear-reminders",
+    "--test": "--clear-tests",
+    "--type-option": "--clear-type-options",
+};
 function assertNoMissingRequiredCreateOptions(params) {
     const { combinedMissingFlags, typeDefinition, missingRequiredCreateFlags, missingRequiredTypeOptionKeys, openStatus, type, createMode, missingRequiredRuntimeFields, } = params;
     if (combinedMissingFlags.length === 0) {
@@ -1359,12 +1369,12 @@ function assertNoMissingRequiredCreateOptions(params) {
     ].join(" ");
     const nextSteps = [
         `Run "pm create --help --type ${type}" for type-aware required option guidance.`,
-    ];
-    if (combinedMissingFlags.includes("--title")) {
-        nextSteps.push('Title can also be passed as the first positional argument (example: pm create "Your title" --type ' +
+        ...combinedMissingFlags
+            .filter((flag) => flag === "--title")
+            .map(() => 'Title can also be passed as the first positional argument (example: pm create "Your title" --type ' +
             type +
-            ").");
-    }
+            ")."),
+    ];
     if (createMode === "strict") {
         nextSteps.push('For staged onboarding, retry with "--create-mode progressive".');
         if (SCHEDULE_CREATE_PRESET_TYPES.has(type)) {
@@ -1374,21 +1384,35 @@ function assertNoMissingRequiredCreateOptions(params) {
     if (runtimeFieldSyntax.length > 0) {
         nextSteps.push(`Required custom field formats: ${runtimeFieldSyntax.map((field) => field.description).join("; ")}.`);
     }
+    const collectionClearFlags = [
+        ...new Set(combinedMissingFlags.flatMap((flag) => {
+            const normalizedFlag = flag.split(" ", 1)[0];
+            const clearFlag = CLEAR_FLAG_BY_REQUIRED_CREATE_FLAG[normalizedFlag];
+            return clearFlag ? [clearFlag] : [];
+        })),
+    ];
+    if (collectionClearFlags.length > 0) {
+        nextSteps.push(`If the truthful value is an empty collection, use ${collectionClearFlags.join(", ")} instead of inventing metadata.`);
+    }
     const errorMessage = combinedMissingFlags.length === 1
         ? `Missing required option ${combinedMissingFlags[0]} for type "${type}"`
         : `Missing required options ${combinedMissingFlags.join(", ")} for type "${type}"`;
     throw new PmCliError(errorMessage, EXIT_CODE.USAGE, {
         code: "missing_required_option",
         required: `Provide all required create options and type options for type "${type}" in one invocation.`,
-        examples: [nextValidExample],
+        examples: [
+            ...collectionClearFlags.map((flag) => `pm create --type ${type} ${flag} ...`),
+            nextValidExample,
+        ],
         nextSteps,
         recovery: createMode === "strict"
             ? {
                 recovery_mode: "compact",
                 missing_required_fields: combinedMissingFlags,
                 suggested_flags: [
-                    "--create-mode progressive",
+                    ...collectionClearFlags,
                     ...combinedMissingFlags,
+                    "--create-mode progressive",
                 ],
             }
             : undefined,
@@ -1926,4 +1950,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=02c41ea1-8d4e-5239-b95a-a07210b63d7f
+//# debugId=c9bfbfd4-3d34-5fa7-b264-6bf9ed5f7f81

package/dist/sdk/linked-artifacts.js

@@ -4,22 +4,21 @@
  * Implements the pm linked artifacts 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]="1832e2b3-0ece-523d-8f38-598303d3f590")}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]="accd0229-6974-5950-8cea-74f517706878")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
 import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
-import { assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, parseCsvKv, } from "../core/item/parse.js";
+import { assertNoAmbiguousBareCommaEntry, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, parseCsvKv, } from "../core/item/parse.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { isRemoteLinkedArtifactReference } from "../core/validate/linked-artifact-reference.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
-import { splitCommaList } from "../core/shared/split-comma-list.js";
 import { stableValueEquals } from "../core/shared/serialization.js";
 import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
+import { resolvePmRoot, resolveWorkspaceRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { SCOPE_VALUES } from "../types/index.js";
 import { resolveAuthor } from "../core/shared/author.js";
@@ -63,7 +62,9 @@ export function looksLikeStructuredPathEntry(raw) {
     // leading assignment syntax through the structured-key allowlist so typos
     // and malformed URL-plus-note input remain atomic failures (GH-258,
     // GH-1000).
-    const equalsIndex = raw.indexOf("=");
+    const firstCommaIndex = raw.indexOf(",");
+    const leadingSegment = raw.slice(0, firstCommaIndex >= 0 ? firstCommaIndex : raw.length);
+    const equalsIndex = leadingSegment.indexOf("=");
     if (equalsIndex >= 0 &&
         !/\s/u.test(raw) &&
         (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(raw) ||
@@ -71,18 +72,7 @@ export function looksLikeStructuredPathEntry(raw) {
             [raw.indexOf("/"), raw.indexOf("\\")].some((separatorIndex) => separatorIndex >= 0 && separatorIndex < equalsIndex))) {
         return false;
     }
-    return raw.includes("=") || looksLikeGenericKeyValueEntry(raw);
-}
-function expandBareCommaSeparatedAddEntries(raw) {
-    return raw.flatMap((entry) => {
-        const trimmed = entry.trim();
-        if (trimmed.length === 0 ||
-            looksLikeStructuredPathEntry(trimmed) ||
-            !trimmed.includes(",")) {
-            return [entry];
-        }
-        return splitCommaList(trimmed);
-    });
+    return leadingSegment.includes("=") || looksLikeGenericKeyValueEntry(raw);
 }
 /** Whether a Markdown destination contains only balanced parentheses. */
 function hasBalancedParentheses(value) {
@@ -136,21 +126,21 @@ export function parseAddEntries(raw, bareNoun) {
             if (reference !== undefined)
                 return [reference];
         }
-        return expandBareCommaSeparatedAddEntries([entry]).map((expanded) => {
-            const expandedTrimmed = expanded.trim();
-            const kv = looksLikeStructuredPathEntry(expandedTrimmed)
-                ? parseCsvKv(expanded, "--add")
-                : { path: expandedTrimmed };
-            assertNoUnknownCsvKeys(kv, "--add", LINKED_ARTIFACT_ADD_KEYS);
-            if (!kv.path) {
-                throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);
-            }
-            return {
+        assertNoAmbiguousBareCommaEntry(trimmed, "--add", `${bareNoun} path`, looksLikeStructuredPathEntry(trimmed));
+        const kv = looksLikeStructuredPathEntry(trimmed)
+            ? parseCsvKv(entry, "--add")
+            : { path: trimmed };
+        assertNoUnknownCsvKeys(kv, "--add", LINKED_ARTIFACT_ADD_KEYS);
+        if (!kv.path) {
+            throw new PmCliError(`--add requires path=<value> or a bare ${bareNoun} path`, EXIT_CODE.USAGE);
+        }
+        return [
+            {
                 path: kv.path,
                 scope: ensureScope(kv.scope),
                 note: kv.note?.trim() || undefined,
-            };
-        });
+            },
+        ];
     });
 }
 /** Implements parse add glob entries for the public runtime surface of this module. */
@@ -439,7 +429,7 @@ async function buildLinkedArtifactResult(params) {
         migrations_applied: params.migrationsApplied && params.migrationsApplied > 0
             ? params.migrationsApplied
             : undefined,
-        validation: params.options.validatePaths
+        validation: params.options.validatePaths || params.changed
             ? await validateLinkedPaths(paths, params.workspaceRoot)
             : undefined,
     };
@@ -538,4 +528,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=1832e2b3-0ece-523d-8f38-598303d3f590
+//# debugId=accd0229-6974-5950-8cea-74f517706878