@unbrained/pm-cli 2026.8.16 → 2026.8.17

package/dist/sdk/guide-topics.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]="3911e4fb-a9b3-5732-8b45-c484a121dffb")}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]="e791d84f-7d4c-59fa-9644-527109dbb596")}catch(e){}}();
 function normalizeTopicToken(value) {
     return value.trim().toLowerCase().replaceAll("_", "-");
 }
@@ -338,6 +338,195 @@ const GUIDE_TOPICS = [
         ],
         related: ["commands", "skills", "workflows"],
     },
+    {
+        id: "tokens",
+        aliases: ["output", "budget", "context-cost", "projections"],
+        title: "Read Output and Token Budgets",
+        summary: "Bound what a read costs before it is emitted, and resume the part a budget withheld.",
+        intent: "Use this when an agent must keep context small: every read declares a token ceiling, degrades deterministically, and reports what it omitted.",
+        commands: [
+            "pm contracts --summary --json",
+            "pm list --status open --output-limit 20",
+            "pm get <ID> --output-include id,title,status,dependencies",
+            "pm context --limit 10 --token-accounting",
+            "pm notes <ID> --output-cursor <cursor>",
+            "pm list-closed --output-budget unbounded",
+        ],
+        workflows: [
+            {
+                name: "Bound A Read Before Emitting It",
+                goal: "Never pay for rows the task does not need.",
+                prompt: "Choose the narrowest projection first, then a row limit, then a token budget. Read the omission receipt before concluding the result is complete.",
+                commands: [
+                    "pm contracts --command list --flags-only --json",
+                    "pm list --status open --output-limit 20 --output-format toon",
+                    "pm list --status open --token-accounting",
+                ],
+            },
+            {
+                name: "Recover A Truncated Read",
+                goal: "Continue a bounded read instead of re-running it unbounded.",
+                prompt: "When output_budget_truncation appears, prefer the declared continuation cursor. Only widen the budget when the response declares no cursor.",
+                commands: [
+                    "pm notes <ID> --output-cursor <cursor>",
+                    "pm get <ID> --output-budget 20000",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/READ_OUTPUT_CONTRACTS.md",
+                purpose: "Budget, truncation, continuation, and omission receipts.",
+            },
+            {
+                path: "docs/OUTPUT_PROJECTION_CONTRACTS.md",
+                purpose: "Field and section projection grammar for every read.",
+            },
+            {
+                path: "docs/OUTPUT_TOKEN_ACCOUNTING.md",
+                purpose: "Per-section token cost receipts.",
+            },
+            {
+                path: "docs/ITEM_READ_PROJECTIONS.md",
+                purpose: "Item-level projection defaults and restore hints.",
+            },
+        ],
+        related: ["commands", "workflows", "quickstart"],
+    },
+    {
+        id: "graph",
+        aliases: ["relationships", "deps", "dependencies", "analytics"],
+        title: "Relationship Graph and Planning Analytics",
+        summary: "Type the relationships between items, then read the project as a graph rather than as a list.",
+        intent: "Use this when the question is about lineage, ordering, blast radius, bottlenecks, or which work reaches a declared outcome.",
+        commands: [
+            "pm deps <ID>",
+            'pm update <ID> --dep "id=<other>,kind=implements"',
+            "pm graph analyze",
+            "pm graph impact <ID> --direction downstream",
+            "pm graph paths <ID> <ID>",
+            "pm graph audit",
+        ],
+        workflows: [
+            {
+                name: "Place New Work In The Ladder",
+                goal: "Every item resolves to an outcome through a typed, explainable path.",
+                prompt: "Set parent lineage first, then add typed edges that cite durable evidence. Never add an edge to satisfy a count.",
+                commands: [
+                    "pm search \"<topic>\" --limit 10",
+                    'pm update <ID> --dep "id=<parent-goal>,kind=implements"',
+                    "pm graph ancestors <ID>",
+                ],
+            },
+            {
+                name: "Assess Blast Radius Before Changing Something",
+                goal: "Know what derives from an item before touching it.",
+                prompt: "Walk the directed graph downstream from the item, then check whether any bottleneck node sits on the path.",
+                commands: [
+                    "pm graph impact <ID> --direction downstream",
+                    "pm graph dominators <ID>",
+                    "pm graph articulation",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/RELATIONSHIP_GRAPH.md",
+                purpose: "Graph model, traversal verbs, and analytics surface.",
+            },
+            {
+                path: "docs/DEPENDENCY_KIND_CONTRACT.md",
+                purpose: "Every typed edge kind, its direction, and its semantics.",
+            },
+        ],
+        related: ["commands", "workflows", "assurance"],
+    },
+    {
+        id: "assurance",
+        aliases: ["gates", "invariants", "measurements", "quality"],
+        title: "Declared Invariants and Gates",
+        summary: "Express a project's own quality rules as tracked data the SDK evaluates, instead of as scripts.",
+        intent: "Use this when a rule must hold over the record itself — a floor, a ceiling, or a monotone property — and must fail closed in CI.",
+        commands: [
+            "pm assurance list",
+            "pm assurance run <gate-id> --trigger ci --dry-run",
+            "pm validate --check-resolution --check-history-drift",
+            "pm health --summary",
+        ],
+        workflows: [
+            {
+                name: "Add An Invariant Rather Than A Script",
+                goal: "A new enforcement gap becomes declared data, not a new bespoke gate script.",
+                prompt: "Define the measurement, bind an assertion with an explicit bound and polarity, prove a negative control, then attach it to a trigger.",
+                commands: [
+                    "pm assurance list --json",
+                    "pm assurance run <gate-id> --trigger ci --dry-run --json",
+                ],
+            },
+            {
+                name: "Read A Verdict Before Believing It",
+                goal: "Know which population a passing assertion speaks for.",
+                prompt: "Read population_size and scope on every assertion. A gate that cannot fail for the reason it exists is not evidence.",
+                commands: [
+                    "pm assurance run <gate-id> --trigger ci --dry-run --json --output-budget unbounded",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/ASSURANCE.md",
+                purpose: "Measurement, assertion, gate, and trigger vocabulary.",
+            },
+            {
+                path: "docs/MUTATION_INTEGRITY.md",
+                purpose: "What every mutation must record to remain provable.",
+            },
+        ],
+        related: ["release", "graph", "workflows"],
+    },
+    {
+        id: "merge",
+        aliases: ["branches", "concurrency", "multi-agent", "fleet"],
+        title: "Branching, Merging, and Concurrent Agents",
+        summary: "Keep tracker data and history conflict-free while many agents work on separate branches.",
+        intent: "Use this when more than one agent or worktree mutates the same tracker and the results must merge without hand resolution.",
+        commands: [
+            "pm merge install",
+            "pm claim <ID>",
+            "pm release <ID>",
+            "pm validate --check-history-drift",
+            "pm health --check-only",
+        ],
+        workflows: [
+            {
+                name: "Prepare A Clone For Field-Aware Merges",
+                goal: "The committed merge fence needs clone-local driver configuration once.",
+                prompt: "Run the merge installer in every fresh clone or worktree before the first branch merge of tracker data.",
+                commands: ["pm merge install", "pm health --check-only"],
+            },
+            {
+                name: "Hand Work Between Agents Safely",
+                goal: "Ownership and evidence survive the handoff.",
+                prompt: "Claim before substantial edits, record evidence as comments, and release the claim when pausing, handing off, closing, or canceling.",
+                commands: [
+                    "pm claim <ID>",
+                    'pm comments <ID> "Handoff: <state and next step>"',
+                    "pm release <ID>",
+                ],
+            },
+        ],
+        docs: [
+            {
+                path: "docs/MERGE_SAFETY.md",
+                purpose: "Merge driver, field-aware resolution, and clone setup.",
+            },
+            {
+                path: "docs/SDK_CONTEXT_COORDINATION.md",
+                purpose: "Coordination primitives for concurrent agents.",
+            },
+        ],
+        related: ["workflows", "assurance", "commands"],
+    },
 ];
 const TOPIC_BY_TOKEN = new Map();
 for (const topic of GUIDE_TOPICS) {
@@ -376,4 +565,4 @@ export function resolveGuideTopic(rawTopic) {
     return TOPIC_BY_TOKEN.get(normalized) ?? null;
 }
 //# sourceMappingURL=guide-topics.js.map
-//# debugId=3911e4fb-a9b3-5732-8b45-c484a121dffb
+//# debugId=e791d84f-7d4c-59fa-9644-527109dbb596

package/dist/sdk/index.d.ts

@@ -36,6 +36,7 @@ export { isRuntimeRecord } from "./runtime-input.js";
 export { resolveStartTaskInProgressStatus } from "./start-task-status.js";
 export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, resolveProjectMergeTypeFolders, runMergeInstall, type MergeFenceAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./merge/install.js";
 export { deriveSchemaEvolutionMigrationId, formatSchemaEvolutionMigrationHuman, planSchemaEvolutionMigration, runSchemaEvolutionMigration, type PlanSchemaEvolutionMigrationOptions, type SchemaEvolutionFieldChange, type SchemaEvolutionItemPlan, type SchemaEvolutionMigrationPlan, } from "./schema-migration.js";
+export type { RuntimeFieldDefinition, RuntimeFieldValueSchema, } from "./schema.js";
 export { runWithActiveExtensions, type ActiveExtensionScopeOptions, } from "./runtime.js";
 export { applyInvocationAuthorOverride } from "./invocation-author.js";
 export { evaluateMutationGuard, getMutationActionContract, isMutationAction, listMutationActions, PM_MUTATION_ACTION_CONTRACTS, scanMutationSecrets, type EvaluateMutationGuardOptions, type MutationActionContract, type MutationGuardResult, type MutationGuardSettings, type MutationHistoryScope, type SecretGuardFinding, type SecretGuardMode, } from "./mutation-guard.js";
@@ -60,6 +61,8 @@ export * from "./governance/assurance.js";
 export * from "./governance/assurance-action.js";
 export * from "./governance/assurance-runtime.js";
 export * from "./governance/assurance-presets.js";
+export * from "./governance/boundary-fixtures.js";
+export * from "./governance/defect-recurrence.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.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]="9ec91496-fc1e-5be5-a8e8-145d884b0ef7")}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]="fe5e55c6-aabb-53c7-bdbb-16f2ea78f180")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -58,6 +58,8 @@ export * from "./governance/assurance.js";
 export * from "./governance/assurance-action.js";
 export * from "./governance/assurance-runtime.js";
 export * from "./governance/assurance-presets.js";
+export * from "./governance/boundary-fixtures.js";
+export * from "./governance/defect-recurrence.js";
 export * from "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -152,4 +154,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=9ec91496-fc1e-5be5-a8e8-145d884b0ef7
+//# debugId=fe5e55c6-aabb-53c7-bdbb-16f2ea78f180

package/dist/sdk/lifecycle/create.js

@@ -4,7 +4,7 @@
  * 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]="ffa56c1a-d98c-566a-81c5-4ad5608aa26c")}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]="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";
 import { requireTerminalReasonWithRecovery } from "../lifecycle-policy.js";
 import { evaluateSimilarityGovernance, similarityAdvisoryWarnings, } from "../similarity.js";
@@ -1700,6 +1700,8 @@ export async function runCreate(options, global) {
         itemFormat: settings.item_format,
         typeToFolder: typeRegistry.type_to_folder,
         allowUnresolved: resolvedOptions.allowUnresolvedDeps,
+        holders: [{ id, createdAt: nowValue }],
+        schema: settings.schema,
     })));
     status = blockedByResolution.status;
     const blockedReason = resolveUnsettableOptionalString(unsetKeys, "blocked_reason", resolvedOptions.blockedReason);
@@ -1888,4 +1890,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=ffa56c1a-d98c-566a-81c5-4ad5608aa26c
+//# debugId=7d69bb56-9fab-5059-9357-5b6bea2078b9

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

@@ -4,7 +4,7 @@
  * Implements the pm update 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]="0f91de58-2cbc-52ba-97ea-42482d0c6ce1")}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]="e797d654-df89-554b-876b-cb2faa350bd0")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, toItemRecord, applyAcceptanceCriteriaMutations, applyTagRemovals, mergeAdditiveTags, parseOptionalNonNegativeInteger, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, resolveItemTypeRegistry, resolveTypeName, collectRuntimeUpdateFieldValues, buildInvalidTypeError, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, stableValueEquals, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { assertDependencyTargetsResolvable } from "../dependency-flag-validation.js";
 import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
@@ -818,6 +818,19 @@ export const runUpdateMany = async (options, global) => {
         updateSummary,
         dependencyWarnings,
     });
+    await assertDependencyTargetsResolvable({
+        pmRoot: runtime.pmRoot,
+        dependencies: parseDependencyAdditions(options.update.dep, runtime.settings.id_prefix, nowIso(), resolveAuthor(options.update.author, runtime.settings.author_default)).additions,
+        idPrefix: runtime.settings.id_prefix,
+        itemFormat: runtime.settings.item_format,
+        typeToFolder: resolveItemTypeRegistry(runtime.settings, getActiveExtensionRegistrations()).type_to_folder,
+        allowUnresolved: options.update.allowUnresolvedDeps,
+        holders: plan.listed.items.map((item) => ({
+            id: item.id,
+            createdAt: item.created_at,
+        })),
+        schema: runtime.settings.schema,
+    });
     return options.dryRun === true
         ? buildUpdateManyDryRunResult(plan)
         : applyUpdateManyPlan({ runtime, options, global, plan });
@@ -840,4 +853,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=0f91de58-2cbc-52ba-97ea-42482d0c6ce1
+//# debugId=e797d654-df89-554b-876b-cb2faa350bd0

package/dist/sdk/lifecycle/update.js

@@ -4,7 +4,7 @@
  * Implements the pm update 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]="244583b8-2ffd-5da4-a4d3-46396fb354c0")}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]="a421c150-13a9-5334-85a4-5b3199a5d2c7")}catch(e){}}();
 import { pathExists, COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { runClose } from "./close.js";
 import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parseRegressionInput, } from "./metadata-normalizers.js";
@@ -1743,6 +1743,7 @@ export async function runUpdate(id, options, global) {
     const nowValue = new Date();
     const nowIso = nowValue.toISOString();
     const dependencyUpdates = parseDependencyAdditions(options.dep, settings.id_prefix, nowIso, author);
+    assertDependencyEdgesAllowed(id, dependencyUpdates.additions);
     const dependencyTargetWarnings = await assertDependencyTargetsResolvable({
         pmRoot,
         dependencies: dependencyUpdates.additions,
@@ -1750,6 +1751,8 @@ export async function runUpdate(id, options, global) {
         itemFormat: settings.item_format,
         typeToFolder: typeRegistry.type_to_folder,
         allowUnresolved: options.allowUnresolvedDeps,
+        holders: [{ id }],
+        schema: settings.schema,
     });
     const dependencyRemovals = parseDependencyRemovals(options.depRemove, settings.id_prefix);
     const parsedCommentUpdates = parseLogSeed("--comment", options.comment, nowIso, author);
@@ -1897,4 +1900,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=244583b8-2ffd-5da4-a4d3-46396fb354c0
+//# debugId=a421c150-13a9-5334-85a4-5b3199a5d2c7

package/dist/sdk/linked-artifacts.js

@@ -4,7 +4,7 @@
  * 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]="256b39b7-882e-553c-9dea-813bfd363dd7")}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]="72f57c4d-65c5-57f1-a16a-f6c970aca680")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
@@ -83,24 +83,73 @@ function expandBareCommaSeparatedAddEntries(raw) {
         return splitCommaList(trimmed);
     });
 }
+/** Whether a Markdown destination contains only balanced parentheses. */
+function hasBalancedParentheses(value) {
+    let depth = 0;
+    for (const character of value) {
+        if (character === "(")
+            depth += 1;
+        if (character === ")")
+            depth -= 1;
+        if (depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Parse one lossless bare, Markdown, or CSV-label remote documentation reference. */
+function parseDocumentationReference(trimmed) {
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(trimmed) &&
+        !looksLikeStructuredPathEntry(trimmed)) {
+        return { path: trimmed, scope: "project", note: undefined };
+    }
+    const labelEnd = trimmed.indexOf("](");
+    if (trimmed.startsWith("[") && labelEnd > 0 && trimmed.endsWith(")")) {
+        const destination = trimmed.slice(labelEnd + 2, -1).trim();
+        if (destination.length > 0 && hasBalancedParentheses(destination)) {
+            return {
+                path: destination,
+                scope: "project",
+                note: trimmed.slice(1, labelEnd).trim() || undefined,
+            };
+        }
+    }
+    const delimiterIndex = trimmed.indexOf(",");
+    if (delimiterIndex < 0)
+        return undefined;
+    const label = trimmed.slice(0, delimiterIndex).trim();
+    const destination = trimmed.slice(delimiterIndex + 1).trim();
+    if (label.length === 0 ||
+        !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(destination)) {
+        return undefined;
+    }
+    return { path: destination, scope: "project", note: label };
+}
 /** Implements parse add entries for the public runtime surface of this module. */
 export function parseAddEntries(raw, bareNoun) {
     if (!raw)
         return [];
-    return expandBareCommaSeparatedAddEntries(raw).map((entry) => {
+    return raw.flatMap((entry) => {
         const trimmed = entry.trim();
-        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);
+        if (bareNoun === "doc") {
+            const reference = parseDocumentationReference(trimmed);
+            if (reference !== undefined)
+                return [reference];
         }
-        return {
-            path: kv.path,
-            scope: ensureScope(kv.scope),
-            note: kv.note?.trim() || undefined,
-        };
+        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 {
+                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. */
@@ -490,4 +539,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=256b39b7-882e-553c-9dea-813bfd363dd7
+//# debugId=72f57c4d-65c5-57f1-a16a-f6c970aca680

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

@@ -19,6 +19,8 @@ interface ClaimStateContext {
     last_release: ClaimHistoryContext | null;
 }
 type GetItemProjection = Partial<ItemMetadata> & {
+    /** Canonical item identity retained by every depth and field projection. */
+    id: string;
     body?: string;
     /** Number of notes omitted by a token-bounded projection. */
     notes_count?: number;

package/dist/sdk/query/get.js

@@ -4,7 +4,7 @@
  * Implements the SDK-owned item query 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]="89176e36-40ea-5ec2-b291-d1cf042c4140")}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]="c35e787c-a9a1-5ffa-9dcf-62780fceed4c")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
 import { recordContextUsageTouches } from "../context-usage.js";
@@ -44,7 +44,10 @@ function itemMaterialFieldGroups(item, body) {
     return [
         ...(body.length > 0 ? ["body"] : []),
         ...Object.entries(collectionCounts).flatMap(([name, count]) => count > 0 ? [name] : []),
-        ...(collectionCounts.files + collectionCounts.tests + collectionCounts.docs > 0
+        ...(collectionCounts.files +
+            collectionCounts.tests +
+            collectionCounts.docs >
+            0
             ? ["linked"]
             : []),
         "children",
@@ -195,6 +198,30 @@ function validateGetFields(fields, runtimeMetadataKeys) {
         });
     }
 }
+const EMPTY_PROJECTED_COLLECTION_FIELDS = new Set([
+    "comments",
+    "notes",
+    "learnings",
+    "files",
+    "tests",
+    "test_runs",
+    "docs",
+    "reminders",
+    "events",
+    "dependencies",
+    "plan_steps",
+    "plan_decisions",
+    "plan_discoveries",
+    "plan_validation",
+]);
+/** Resolve one projected metadata value while distinguishing an empty requested collection from an omitted field. */
+function projectedMetadataValue(source, counts, field) {
+    if (Object.hasOwn(counts, field))
+        return counts[field];
+    if (source[field] !== undefined)
+        return source[field];
+    return EMPTY_PROJECTED_COLLECTION_FIELDS.has(field) ? [] : undefined;
+}
 function projectItemForFields(item, fields) {
     const source = toItemRecord(item);
     const omittedCounts = {
@@ -202,7 +229,7 @@ function projectItemForFields(item, fields) {
         tests_count: item.tests?.length ?? 0,
         collection_counts: itemCollectionCounts(item),
     };
-    const projected = {};
+    const projected = { id: item.id };
     for (const field of fields) {
         const normalized = normalizeGetField(field);
         if (normalized === "body" ||
@@ -216,9 +243,7 @@ function projectItemForFields(item, fields) {
             normalized.startsWith("schedule.")) {
             continue;
         }
-        projected[normalized] = Object.hasOwn(omittedCounts, normalized)
-            ? omittedCounts[normalized]
-            : source[normalized];
+        projected[normalized] = projectedMetadataValue(source, omittedCounts, normalized);
     }
     return projected;
 }
@@ -438,4 +463,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=89176e36-40ea-5ec2-b291-d1cf042c4140
+//# debugId=c35e787c-a9a1-5ffa-9dcf-62780fceed4c