@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/dist/sdk/graph/governance.d.ts

@@ -14,10 +14,10 @@
  */
 import type { RelationshipEdge } from "../relationships.js";
 import type { WorkspaceRelationshipAssembly } from "./assembly.js";
+import { type RelationshipAuditFindingCode } from "./governance-contracts.js";
+export type { RelationshipAuditFindingCode } from "./governance-contracts.js";
 /** Severity ladder shared by every relationship audit finding. */
 export type RelationshipAuditSeverity = "error" | "warning" | "info";
-/** Machine-readable identifier for one relationship audit finding family. */
-export type RelationshipAuditFindingCode = "missing_reference_active" | "missing_reference_terminal" | "legacy_no_blocker_sentinel" | "ordering_cycle" | "legacy_ordering_cycle" | "duplicate_edge" | "legacy_duplicate_edge" | "duplicate_dependency_row" | "legacy_duplicate_dependency_row" | "stale_lifecycle_block" | "isolated_active_node" | "sparse_active_node";
 /** One policy-aware relationship audit finding with bounded evidence. */
 export interface RelationshipAuditFinding {
     /** Machine-readable finding family identifier. */
@@ -56,6 +56,12 @@ export interface RelationshipCoverageProfile {
     edge_basis: "deduplicated_directed";
     /** Deterministic per-kind edge counts. */
     edges_by_kind: Record<string, number>;
+    /** Per-kind share of all deduplicated directed edges. */
+    edge_share_by_kind: Record<string, number>;
+    /** Edges carrying discovery, provenance, incident, or verification semantics. */
+    semantic_edges: number;
+    /** Share of all edges carrying discovery, provenance, incident, or verification semantics. */
+    semantic_edge_share: number;
     /** Nodes whose lifecycle status is active (non-terminal, non-missing). */
     active_nodes: number;
     /** Materialized placeholder nodes for referenced-but-absent items. */
@@ -66,6 +72,34 @@ export interface RelationshipCoverageProfile {
     degree_leq_one_active_nodes: number;
     /** Deterministic per-type connectivity coverage; untyped nodes bucket under `(untyped)`. */
     coverage_by_type: Record<string, RelationshipCoverageTypeProfile>;
+    /** Undirected cut vertices whose removal increases the component count. */
+    articulation_points: number;
+    /** Undirected cut edges whose removal disconnects their endpoints. */
+    bridge_edges: number;
+    /** Milestone nodes whose title explicitly declares an outcome. */
+    outcome_nodes: number;
+    /** Active non-outcome nodes with a typed hierarchy or implements path to an outcome. */
+    active_outcome_reachable_nodes: number;
+    /** Active non-outcome nodes without a typed hierarchy or implements path to an outcome. */
+    active_outcome_unreachable_nodes: number;
+    /** Active typed-outcome reachability expressed as integer basis points. */
+    active_outcome_reachability_basis_points: number;
+    /** Terminal non-placeholder, non-outcome nodes included in the all-status census. */
+    terminal_nodes: number;
+    /** Terminal non-outcome nodes with a typed hierarchy or implements path to an outcome. */
+    terminal_outcome_reachable_nodes: number;
+    /** Terminal non-outcome nodes without a typed hierarchy or implements path to an outcome. */
+    terminal_outcome_unreachable_nodes: number;
+    /** Terminal typed-outcome reachability expressed as integer basis points. */
+    terminal_outcome_reachability_basis_points: number;
+    /** All active and terminal non-outcome nodes with a typed path to an outcome. */
+    outcome_reachable_nodes: number;
+    /** All active and terminal non-outcome nodes without a typed path to an outcome. */
+    outcome_unreachable_nodes: number;
+    /** All-status typed-outcome reachability expressed as integer basis points. */
+    outcome_reachability_basis_points: number;
+    /** Affected-subject census containing every known finding code, including zero populations. */
+    finding_subjects_by_code: Record<RelationshipAuditFindingCode, number>;
 }
 /** Tuning and policy inputs accepted by the relationship audit. */
 export interface RelationshipAuditOptions {
@@ -89,6 +123,8 @@ export interface RelationshipAuditReport {
     /** Structural coverage metrics computed during the audit. */
     profile: RelationshipCoverageProfile;
 }
+/** Return whether a relationship kind carries provenance or verification context. */
+export declare function isSemanticContextKind(kind: string): boolean;
 /**
  * Enumerate strongly connected components with more than one member (or a
  * self-loop) over an ordering-only successor digraph using an iterative Tarjan
@@ -165,6 +201,12 @@ export interface RelationshipAuditDelta {
         degree_leq_one_active_nodes: number;
         /** Signed per-kind edge-count deltas; unchanged kinds are dropped. */
         edges_by_kind: Record<string, number>;
+        /** Signed per-kind edge-share deltas; unchanged kinds are dropped. */
+        edge_share_by_kind: Record<string, number>;
+        /** Change in semantic-context edge count. */
+        semantic_edges: number;
+        /** Change in semantic-context edge share. */
+        semantic_edge_share: number;
         /** Signed per-type coverage deltas; unchanged types are dropped. */
         coverage_by_type: Record<string, RelationshipCoverageTypeProfile>;
     };

package/dist/sdk/graph/governance.js

@@ -1,8 +1,24 @@
 
-!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]="76fa19c7-a421-5026-8de8-450285987c4e")}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]="ab8a4904-0302-5e36-9963-750b3ba79876")}catch(e){}}();
 import { isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
+import { findRelationshipCutStructure } from "./centrality.js";
+import { RELATIONSHIP_AUDIT_FINDING_CODES, } from "./governance-contracts.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
+/** Canonical item type and title marker that identify explicit outcomes. */
+const OUTCOME_MILESTONE_TYPE = "milestone";
+const OUTCOME_MILESTONE_TITLE_PREFIX = "outcome milestone:";
+/** Relationship kinds that preserve why work exists or how evidence supports it. */
+const SEMANTIC_CONTEXT_KINDS = new Set([
+    "discovered_from",
+    "incident_from",
+    "supersedes",
+    "verifies",
+]);
+/** Return whether a relationship kind carries provenance or verification context. */
+export function isSemanticContextKind(kind) {
+    return SEMANTIC_CONTEXT_KINDS.has(kind);
+}
 /** Rank used to order findings by decreasing severity. */
 const SEVERITY_RANK = {
     error: 0,
@@ -279,6 +295,104 @@ function collectDuplicateRowFindings(assembly, maxSampleSize) {
     appendFinding(findings, legacy, maxSampleSize, "legacy_duplicate_dependency_row", "info", "Identical repeated dependency rows on terminal holders are historical storage noise with no scheduling effect.", (count) => `${count} exactly duplicated stored dependency row(s) on terminal holder(s)`, "Leave as history debt or clean up in a dedicated changelog-safe closed-item batch.");
     return findings;
 }
+/** Build the reverse typed paths that can carry context toward an outcome. */
+function buildOutcomeReverseIndex(assembly, signal) {
+    const reverse = new Map();
+    for (const edge of assembly.graph.edges()) {
+        signal?.throwIfAborted();
+        const definition = assembly.graph.registry().require(edge.kind);
+        let oriented;
+        if (definition.hierarchy) {
+            oriented = orientTransitiveEdge(edge, definition);
+        }
+        else if (definition.kind === "implements") {
+            oriented = { from: edge.source, to: edge.target };
+        }
+        if (oriented === undefined)
+            continue;
+        const sources = reverse.get(oriented.to) ?? new Set();
+        sources.add(oriented.from);
+        reverse.set(oriented.to, sources);
+    }
+    return reverse;
+}
+/** Expand outcome nodes through every deterministic reverse typed path. */
+function expandOutcomeReachability(outcomes, reverse, signal) {
+    const reachable = new Set(outcomes);
+    const queue = [...outcomes].sort();
+    for (let index = 0; index < queue.length; index += 1) {
+        signal?.throwIfAborted();
+        for (const source of [...(reverse.get(queue[index]) ?? [])].sort()) {
+            if (reachable.has(source))
+                continue;
+            reachable.add(source);
+            queue.push(source);
+        }
+    }
+    return reachable;
+}
+/** Count active and terminal nodes against the resolved outcome-reachable set. */
+function tallyOutcomeReachability(nodeStates, outcomes, reachable, signal) {
+    let activeReachable = 0;
+    let activeUnreachable = 0;
+    let terminal = 0;
+    let terminalReachable = 0;
+    for (const state of nodeStates.values()) {
+        signal?.throwIfAborted();
+        if (outcomes.has(state.id))
+            continue;
+        if (state.missing || state.status === "external")
+            continue;
+        if (state.terminal) {
+            terminal += 1;
+            if (reachable.has(state.id))
+                terminalReachable += 1;
+            continue;
+        }
+        if (reachable.has(state.id))
+            activeReachable += 1;
+        else
+            activeUnreachable += 1;
+    }
+    const active = activeReachable + activeUnreachable;
+    const terminalUnreachable = terminal - terminalReachable;
+    const outcomeReachable = activeReachable + terminalReachable;
+    const outcomeUnreachable = activeUnreachable + terminalUnreachable;
+    const outcomePopulation = outcomeReachable + outcomeUnreachable;
+    return {
+        active_outcome_reachable_nodes: activeReachable,
+        active_outcome_unreachable_nodes: activeUnreachable,
+        active_outcome_reachability_basis_points: active === 0 ? 0 : Math.floor((activeReachable * 10_000) / active),
+        terminal_nodes: terminal,
+        terminal_outcome_reachable_nodes: terminalReachable,
+        terminal_outcome_unreachable_nodes: terminalUnreachable,
+        terminal_outcome_reachability_basis_points: terminal === 0 ? 0 : Math.floor((terminalReachable * 10_000) / terminal),
+        outcome_reachable_nodes: outcomeReachable,
+        outcome_unreachable_nodes: outcomeUnreachable,
+        outcome_reachability_basis_points: outcomePopulation === 0
+            ? 0
+            : Math.floor((outcomeReachable * 10_000) / outcomePopulation),
+    };
+}
+/**
+ * Count nodes with an explicit typed path to an outcome milestone. Hierarchy
+ * edges flow child to parent and `implements` flows implementation to outcome;
+ * unrelated association edges deliberately contribute no reachability.
+ */
+function profileOutcomeReachability(assembly, nodeStates, signal) {
+    const outcomes = new Set(assembly.details
+        .filter((detail) => detail.type?.toLowerCase() === OUTCOME_MILESTONE_TYPE &&
+        detail.title
+            .trim()
+            .toLowerCase()
+            .startsWith(OUTCOME_MILESTONE_TITLE_PREFIX))
+        .map((detail) => detail.id));
+    const reachable = expandOutcomeReachability(outcomes, buildOutcomeReverseIndex(assembly, signal), signal);
+    return {
+        outcome_nodes: outcomes.size,
+        ...tallyOutcomeReachability(nodeStates, outcomes, reachable, signal),
+    };
+}
 /** Fold one active node's degree into the aggregate and per-type coverage tallies. */
 function tallyActiveCoverageNode(tallies, state, degree, exemptIsolates, isolateExemptTypes) {
     tallies.active += 1;
@@ -305,7 +419,7 @@ function tallyActiveCoverageNode(tallies, state, degree, exemptIsolates, isolate
     else
         tallies.sparse.push(state.id);
 }
-function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExemptTypes, maxSampleSize, edgesByKind) {
+function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExemptTypes, maxSampleSize, edgesByKind, signal) {
     const tallies = {
         active: 0,
         missing: 0,
@@ -316,6 +430,7 @@ function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExem
         byType: new Map(),
     };
     for (const id of assembly.graph.nodes()) {
+        signal?.throwIfAborted();
         const state = nodeStates.get(id);
         /* c8 ignore next -- every graph node originates from assembly details by construction */
         if (!state)
@@ -332,18 +447,35 @@ function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExem
     const findings = [];
     appendFinding(findings, isolates, maxSampleSize, "isolated_active_node", "warning", "Active work should be reachable from the graph unless explicitly declared a valid isolate.", (count) => `${count} active item(s) with no relationships`, "Link the item to its parent, prerequisite, or origin — or register it as an exempt isolate.");
     appendFinding(findings, sparse, maxSampleSize, "sparse_active_node", "info", "Active items with a single edge often miss an honest semantic partner; sparse is not automatically defective.", (count) => `${count} active item(s) with exactly one relationship`, "Investigate for an honest second edge (story->task, defect family, cross-epic complement); do not fabricate one.");
+    const edgeCount = assembly.graph.edges().length;
+    const sortedEdgesByKind = Object.fromEntries(Object.entries(edgesByKind).sort(([left], [right]) => left.localeCompare(right)));
+    const semanticEdges = Object.entries(sortedEdgesByKind).reduce((count, [kind, value]) => count + (isSemanticContextKind(kind) ? value : 0), 0);
+    const cutStructure = findRelationshipCutStructure(assembly.graph, {
+        signal,
+    }).value;
+    const outcomeReachability = profileOutcomeReachability(assembly, nodeStates, signal);
     return {
         findings,
         profile: {
             nodes: assembly.graph.nodes().length,
-            edges: assembly.graph.edges().length,
+            edges: edgeCount,
             edge_basis: "deduplicated_directed",
-            edges_by_kind: Object.fromEntries(Object.entries(edgesByKind).sort(([left], [right]) => left.localeCompare(right))),
+            edges_by_kind: sortedEdgesByKind,
+            edge_share_by_kind: Object.fromEntries(Object.entries(sortedEdgesByKind).map(([kind, count]) => [
+                kind,
+                count / edgeCount,
+            ])),
+            semantic_edges: semanticEdges,
+            semantic_edge_share: edgeCount === 0 ? 0 : semanticEdges / edgeCount,
             active_nodes: tallies.active,
             missing_nodes: tallies.missing,
             isolated_active_nodes: tallies.isolated,
             degree_leq_one_active_nodes: tallies.degreeLeqOne,
             coverage_by_type: Object.fromEntries([...tallies.byType.entries()].sort(([left], [right]) => left < right ? -1 : 1)),
+            articulation_points: cutStructure.articulationPoints.length,
+            bridge_edges: cutStructure.bridges.length,
+            ...outcomeReachability,
+            finding_subjects_by_code: Object.fromEntries(RELATIONSHIP_AUDIT_FINDING_CODES.map((code) => [code, 0])),
         },
     };
 }
@@ -390,14 +522,21 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
     options.signal?.throwIfAborted();
     findings.push(...collectDuplicateEdgeFindings(assembly, nodeStates, maxSampleSize), ...collectDuplicateRowFindings(assembly, maxSampleSize));
     options.signal?.throwIfAborted();
-    const coverage = collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExemptTypes, maxSampleSize, edgesByKind);
+    const coverage = collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExemptTypes, maxSampleSize, edgesByKind, options.signal);
     findings.push(...coverage.findings);
     findings.sort((left, right) => SEVERITY_RANK[left.severity] - SEVERITY_RANK[right.severity] ||
         left.code.localeCompare(right.code) ||
         left.sample[0].localeCompare(right.sample[0]));
+    const findingSubjectsByCode = coverage.profile.finding_subjects_by_code;
+    for (const finding of findings) {
+        findingSubjectsByCode[finding.code] += finding.count;
+    }
     return {
         findings,
-        profile: coverage.profile,
+        profile: {
+            ...coverage.profile,
+            finding_subjects_by_code: findingSubjectsByCode,
+        },
     };
 }
 /** Subtract two count records, keeping only non-zero signed deltas in sorted key order. */
@@ -437,16 +576,18 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
         ]),
     ].sort();
     for (const type of typeKeys) {
-        const before = baselineCoverageByType[type];
-        const after = currentCoverageByType[type];
+        const before = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, baselineCoverageByType[type]);
+        const after = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, currentCoverageByType[type]);
         const delta = {
-            active: (after?.active ?? 0) - (before?.active ?? 0),
-            isolated: (after?.isolated ?? 0) - (before?.isolated ?? 0),
-            degree_leq_one: (after?.degree_leq_one ?? 0) - (before?.degree_leq_one ?? 0),
+            active: after.active - before.active,
+            isolated: after.isolated - before.isolated,
+            degree_leq_one: after.degree_leq_one - before.degree_leq_one,
         };
         if (Object.values(delta).some((value) => value !== 0))
             coverageByType[type] = delta;
     }
+    const { edge_share_by_kind: baselineEdgeShareByKind = {}, semantic_edges: baselineSemanticEdges = 0, semantic_edge_share: baselineSemanticEdgeShare = 0, } = baseline.profile;
+    const { edge_share_by_kind: currentEdgeShareByKind = {}, semantic_edges: currentSemanticEdges = 0, semantic_edge_share: currentSemanticEdgeShare = 0, } = current.profile;
     return {
         baseline_saved_at: baseline.saved_at,
         same_snapshot: baseline.fingerprint === current.fingerprint,
@@ -461,9 +602,12 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
             degree_leq_one_active_nodes: current.profile.degree_leq_one_active_nodes -
                 baseline.profile.degree_leq_one_active_nodes,
             edges_by_kind: diffCountRecords(baseline.profile.edges_by_kind, current.profile.edges_by_kind),
+            edge_share_by_kind: diffCountRecords(baselineEdgeShareByKind, currentEdgeShareByKind),
+            semantic_edges: currentSemanticEdges - baselineSemanticEdges,
+            semantic_edge_share: currentSemanticEdgeShare - baselineSemanticEdgeShare,
             coverage_by_type: coverageByType,
         },
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=76fa19c7-a421-5026-8de8-450285987c4e
+//# debugId=ab8a4904-0302-5e36-9963-750b3ba79876

package/dist/sdk/guide.js

@@ -4,7 +4,8 @@
  * Implements the pm guide 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]="9376fbdf-c942-5fa6-9252-92125ae44e73")}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]="27be0fa5-1c6a-53de-a0e8-179aab7c795a")}catch(e){}}();
+import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveConfiguredPmPackageRoot, EXIT_CODE, PmCliError, } from "./runtime-primitives.js";
@@ -119,8 +120,7 @@ async function renderGuideDocs(topic, depth, packageRoot) {
             }
         }
         catch (error) {
-            const code = error?.code;
-            const missing = code === "ENOENT";
+            const missing = isFileAbsentError(error);
             docs.push({
                 path: doc.path,
                 purpose: doc.purpose,
@@ -277,4 +277,4 @@ export function renderGuideMarkdown(result) {
     return lines.join("\n");
 }
 //# sourceMappingURL=guide.js.map
-//# debugId=9376fbdf-c942-5fa6-9252-92125ae44e73
+//# debugId=27be0fa5-1c6a-53de-a0e8-179aab7c795a

package/dist/sdk/index.d.ts

@@ -58,6 +58,7 @@ export * from "./compose.js";
 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 "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -94,7 +95,7 @@ export { runDeps, type DepsCollapseMode, type DepsFormat, type DepsGraphEdge, ty
 export * from "./graph/index.js";
 export { runDocs } from "./docs.js";
 export { runFiles, runFilesDiscover, runFilesLookup, type FilesDiscoveryCandidate, type FilesLookupItem, type FilesLookupMatch, } from "./files.js";
-export { applyPathMigrations, applyStandaloneNote, artifactKey, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, type AddGlobEntry, type LinkedArtifact, type LinkedArtifactCommandOptions, type LinkedArtifactKindConfig, type LinkedArtifactResult, type LinkedPathValidation, type PathMigration, } from "./linked-artifacts.js";
+export { applyPathMigrations, applyStandaloneNote, artifactKey, assertLinkedArtifactMutationIsUnambiguous, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, type AddGlobEntry, type LinkedArtifact, type LinkedArtifactCommandOptions, type LinkedArtifactKindConfig, type LinkedArtifactResult, type LinkedPathValidation, type PathMigration, } from "./linked-artifacts.js";
 export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
@@ -127,7 +128,7 @@ export type { UpdateManyOperationOptions } from "./lifecycle/update-many.js";
 export { runCreate } from "./lifecycle/create.js";
 export { runPlan } from "./lifecycle/plan.js";
 export { runAppend } from "./lifecycle/append.js";
-export { runClaim, runClaimNext, runRelease } from "./lifecycle/claim.js";
+export { isAlreadyClaimedError, runClaim, runClaimNext, runRelease, } from "./lifecycle/claim.js";
 export { runCloseMany } from "./lifecycle/close-many.js";
 export { runUpdateMany } from "./lifecycle/update-many.js";
 export { runComments } from "./comments.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]="8c96c6f6-f711-559a-bb35-9eeaedc720aa")}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]="8664ab01-dc47-5344-b2d7-9ac315e8a74b")}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";
@@ -56,6 +56,7 @@ export * from "./compose.js";
 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 "./compile-cache.js";
 export * from "./environment/project-runtime-compatibility.js";
 export * from "./environment/source-context.js";
@@ -92,7 +93,7 @@ export { runDeps, } from "./dependencies.js";
 export * from "./graph/index.js";
 export { runDocs } from "./docs.js";
 export { runFiles, runFilesDiscover, runFilesLookup, } from "./files.js";
-export { applyPathMigrations, applyStandaloneNote, artifactKey, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, } from "./linked-artifacts.js";
+export { applyPathMigrations, applyStandaloneNote, artifactKey, assertLinkedArtifactMutationIsUnambiguous, dedupeLinkedArtifacts, ensureScope, expandAddGlobEntries, normalizeLinkedPath, parseAddEntries, parseAddGlobEntries, parseMigrateEntries, parseRemoveEntries, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, validateLinkedPaths, } from "./linked-artifacts.js";
 export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
@@ -119,7 +120,7 @@ export * from "./actionability.js";
 export { runCreate } from "./lifecycle/create.js";
 export { runPlan } from "./lifecycle/plan.js";
 export { runAppend } from "./lifecycle/append.js";
-export { runClaim, runClaimNext, runRelease } from "./lifecycle/claim.js";
+export { isAlreadyClaimedError, runClaim, runClaimNext, runRelease, } from "./lifecycle/claim.js";
 export { runCloseMany } from "./lifecycle/close-many.js";
 export { runUpdateMany } from "./lifecycle/update-many.js";
 export { runComments } from "./comments.js";
@@ -150,4 +151,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=8c96c6f6-f711-559a-bb35-9eeaedc720aa
+//# debugId=8664ab01-dc47-5344-b2d7-9ac315e8a74b

package/dist/sdk/lifecycle/claim.js

@@ -4,7 +4,7 @@
  * 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]="2e9b9321-a892-5bab-b6f8-4717fb5962df")}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]="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";
 import { wrapOwnershipConflict } from "../annotations.js";
 import { describeItemOwnershipConflict } from "../ownership-source.js";
@@ -14,7 +14,14 @@ import { recordClaimSemanticAttribution, recordReleaseSemanticAttribution, } fro
 export const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
 /** Returns whether a failed claim lost the atomic test-and-set race. */
 export function isAlreadyClaimedError(error) {
-    return (error instanceof PmCliError && error.context?.code === "already_claimed_by");
+    if (!(error instanceof Error) || error.name !== "PmCliError") {
+        return false;
+    }
+    const context = error.context;
+    return (typeof context === "object" &&
+        context !== null &&
+        "code" in context &&
+        context.code === "already_claimed_by");
 }
 /** Implements run claim for the public runtime surface of this module. */
 export async function runClaim(id, force, global, options = {}) {
@@ -230,4 +237,4 @@ export async function runRelease(id, force, global, options = {}) {
     };
 }
 //# sourceMappingURL=claim.js.map
-//# debugId=2e9b9321-a892-5bab-b6f8-4717fb5962df
+//# debugId=f70f1329-4dfb-5625-ae0a-66c858d88f7b

package/dist/sdk/linked-artifacts.d.ts

@@ -115,6 +115,8 @@ export declare function parseRemoveEntries(raw: string[] | undefined): string[];
 export declare function parseMigrateEntries(raw: string[] | undefined): PathMigration[];
 /** Implements apply path migrations for the public runtime surface of this module. */
 export declare function applyPathMigrations(artifactPath: string, migrations: PathMigration[]): string;
+/** Reject a transaction that resolves the same linked path into both add and remove sets. */
+export declare function assertLinkedArtifactMutationIsUnambiguous(adds: LinkedArtifact[], removes: string[], migrations?: PathMigration[]): void;
 /** Implements normalize linked path for the public runtime surface of this module. */
 export declare function normalizeLinkedPath(value: string): string;
 /** Anchor a local linked path to the project workspace while preserving remote references and absolute paths. */

package/dist/sdk/linked-artifacts.js

@@ -4,11 +4,11 @@
  * 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]="3fe80124-596b-591c-9f0d-fbbc129c6bb4")}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]="585364aa-e5ff-56b6-8276-8f741fbd6be4")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import fg from "fast-glob";
-import { pathExists } from "../core/fs/fs-utils.js";
+import { isFileAbsentError, pathExists } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, parseCsvKv, } from "../core/item/parse.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
@@ -179,6 +179,30 @@ export function applyPathMigrations(artifactPath, migrations) {
     }
     return next;
 }
+/** Reject a transaction that resolves the same linked path into both add and remove sets. */
+export function assertLinkedArtifactMutationIsUnambiguous(adds, removes, migrations = []) {
+    if (adds.length === 0 || removes.length === 0) {
+        return;
+    }
+    const addedPaths = new Set(adds.map((entry) => applyPathMigrations(entry.path, migrations)));
+    const conflicts = [
+        ...new Set(removes
+            .map((entry) => applyPathMigrations(entry, migrations))
+            .filter((entry) => addedPaths.has(entry))),
+    ].sort((left, right) => left.localeCompare(right));
+    if (conflicts.length === 0) {
+        return;
+    }
+    throw new PmCliError(`Linked artifact mutation cannot add and remove the same normalized path in one transaction: ${conflicts.join(", ")}. Split the replacement into separate commands so each history event has one unambiguous intent.`, EXIT_CODE.USAGE, {
+        code: "linked_artifact_mutation_conflict",
+        reason: "same_path_added_and_removed",
+        required: "Use distinct normalized paths for --add and --remove in one invocation.",
+        why: "Conflicting batch intent cannot be applied deterministically without silently discarding metadata or a removal.",
+        nextSteps: [
+            "Run the removal and addition as separate commands with a --message describing each intent.",
+        ],
+    });
+}
 /** Implements normalize linked path for the public runtime surface of this module. */
 export function normalizeLinkedPath(value) {
     return value.split(path.sep).join("/");
@@ -293,7 +317,7 @@ export async function validateLinkedPaths(paths, workspaceRoot = process.cwd())
             if (typeof error === "object" &&
                 error !== null &&
                 "code" in error &&
-                error.code === "ENOENT") {
+                isFileAbsentError(error)) {
                 missingPaths.push(relativePath);
                 continue;
             }
@@ -384,6 +408,7 @@ export async function runLinkedArtifacts(id, options, global, config) {
     const adds = applyStandaloneNote([...parsedAdds, ...expandedGlobAdds], options.note, parsedAdds.length > 0 || addGlobs.length > 0);
     const removes = parseRemoveEntries(resolvedRemoves).map((entry) => anchorLinkedPath(entry, workspaceRoot, invocationRoot));
     const migrations = parseMigrateEntries(resolvedMigrations);
+    assertLinkedArtifactMutationIsUnambiguous(adds, removes, migrations);
     const shouldMutate = adds.length > 0 || removes.length > 0 || migrations.length > 0;
     if (!shouldMutate) {
         const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
@@ -454,4 +479,4 @@ export function renameArtifactsResultKey(result, key) {
     return out;
 }
 //# sourceMappingURL=linked-artifacts.js.map
-//# debugId=3fe80124-596b-591c-9f0d-fbbc129c6bb4
+//# debugId=585364aa-e5ff-56b6-8276-8f741fbd6be4

package/dist/sdk/merge/driver.d.ts

@@ -30,8 +30,8 @@ export interface MergeDriverResult {
     artifact: MergeDriverArtifact;
     /** Path the merged content was written to. */
     output_path: string;
-    /** Invocation-side preference retained for non-item artifact compatibility. */
-    preferred: MergePreferredSide;
+    /** Invocation-side preference; per-decision retained values remain authoritative. */
+    requested_preference: MergePreferredSide;
     /** Unresolvable conflict labels: metadata field names (item), dotted key paths (json). Empty for history merges. */
     conflicts: string[];
     /** History-merge strategy and entry accounting; present only for the history artifact. */

package/dist/sdk/merge/driver.js

@@ -9,7 +9,7 @@
  * merge never corrupts tracker storage the way raw conflict markers do.
  */
 
-!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]="e739a603-35c5-5df9-8d4b-3bbc0fe3e4fd")}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]="8d79e3a4-6104-5855-837f-69a041b87b27")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
@@ -179,7 +179,7 @@ export async function runMergeDriver(options, global) {
         ok: conflicts.length === 0,
         artifact,
         output_path: outputPath,
-        preferred,
+        requested_preference: preferred,
         conflicts,
         ...result,
         guidance,
@@ -187,4 +187,4 @@ export async function runMergeDriver(options, global) {
     };
 }
 //# sourceMappingURL=driver.js.map
-//# debugId=e739a603-35c5-5df9-8d4b-3bbc0fe3e4fd
+//# debugId=8d79e3a4-6104-5855-837f-69a041b87b27

package/dist/sdk/merge/install.js

@@ -8,7 +8,8 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="94d2a7a8-ce00-5689-b2f6-3d4813234b55")}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]="5e1810a5-04b8-5929-8eee-7a63f1684860")}catch(e){}}();
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -253,7 +254,7 @@ async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
         current = await readFile(gitattributesPath, "utf8");
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -414,7 +415,7 @@ export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
         catch (error) {
             if (error instanceof Error &&
                 "code" in error &&
-                error.code === "ENOENT") {
+                isFileMissingError(error)) {
                 return { status: "not_installed", path: gitattributesPath };
             }
             throw error;
@@ -560,4 +561,4 @@ export async function installMergeFence(options) {
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=94d2a7a8-ce00-5689-b2f6-3d4813234b55
+//# debugId=5e1810a5-04b8-5929-8eee-7a63f1684860

package/dist/sdk/merge/receipts.d.ts

@@ -9,8 +9,10 @@ export interface MergeDecisionReceipt {
     item_path: string;
     /** Item id derived from the merged document path. */
     item_id: string;
-    /** Preferred side used for scalar conflicts. */
-    preferred: MergePreferredSide;
+    /** Side requested by the caller; stable-value decisions can retain either side. */
+    requested_preference?: MergePreferredSide;
+    /** Legacy schema-v1 key accepted while reading older clone-local receipts. */
+    preferred?: MergePreferredSide;
     /** Scalar-conflict selection contract used by the item driver. */
     conflict_resolution: "preferred_side" | "stable_value_order";
     /** Fields selected cleanly from the other branch. */
@@ -42,8 +44,8 @@ export interface MergeDecisionReceiptSummary {
     fields_from_theirs: string[];
     /** Collections combined from both branches. */
     union_fields: string[];
-    /** Preferred side used for scalar conflicts. */
-    preferred: MergePreferredSide;
+    /** Side requested by the caller; decision hashes prove the actual retained values. */
+    requested_preference: MergePreferredSide;
     /** Scalar-conflict selection contract used by the item driver. */
     conflict_resolution: "preferred_side" | "stable_value_order";
     /** Hashes proving the retained and discarded values without publishing them. */