@unbrained/pm-cli 2026.8.30 → 2026.9.1

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health 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]="3c68e4be-fd09-560c-9654-f270e5d7ba73")}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]="76693c03-9395-5bbf-bcc8-fa15e408f30f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
@@ -50,6 +50,7 @@ import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/r
 import { runHistoryRepair } from "../history-repair.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
 import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
+import { buildStatusRoleWarnings, inspectStatusRoleAssignments, } from "./status-role-diagnostics.js";
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
 const STALE_VECTORIZATION_SUMMARY_LIMIT = 25;
 const BRIEF_HEALTH_DETAIL_LIMIT = 8;
@@ -1834,12 +1835,17 @@ function buildDirectoriesHealthCheck(directoryState, strictDirectories) {
         },
     };
 }
-function buildSettingsValuesHealthCheck(settingWarnings) {
+function buildSettingsValuesHealthCheck(settingWarnings, statusRoleDiagnostics) {
     return {
         name: "settings_values",
         status: settingWarnings.length === 0 ? "ok" : "warn",
         ok: settingWarnings.length === 0,
-        details: { warnings: settingWarnings },
+        details: {
+            warnings: settingWarnings,
+            ...(statusRoleDiagnostics.roleless_status_count > 0
+                ? { lifecycle_status_roles: statusRoleDiagnostics }
+                : {}),
+        },
     };
 }
 /** Preserve unknown-author totals for current and legacy scan payloads. */
@@ -2129,7 +2135,7 @@ export async function runHealth(global, options = {}) {
     const strictDirectories = options.strictDirectories === true;
     const refreshPolicy = resolveVectorRefreshPolicy(options);
     const directoryState = await scanHealthDirectories(pmRoot, typeRegistry, strictDirectories);
-    const settingWarnings = validateSettingsValues(settings);
+    const settingsValueWarnings = validateSettingsValues(settings);
     const telemetryCheck = await buildTelemetryCheck(settings, {
         checkTelemetry: options.checkTelemetry === true,
     });
@@ -2144,6 +2150,11 @@ export async function runHealth(global, options = {}) {
         itemReadWarnings,
     });
     const itemsWithBody = items;
+    const statusRoleDiagnostics = inspectStatusRoleAssignments(resolveRuntimeStatusRegistry(settings.schema), items);
+    const settingWarnings = [
+        ...settingsValueWarnings,
+        ...buildStatusRoleWarnings(statusRoleDiagnostics),
+    ];
     const historyPolicy = skipPolicy.skipDrift
         ? { warnings: [] }
         : await enforceHistoryStreamPolicyForItems({
@@ -2197,7 +2208,7 @@ export async function runHealth(global, options = {}) {
     const checks = [
         buildSettingsHealthCheck(settingsPath, settings, normalizedSettingsReadWarnings),
         buildDirectoriesHealthCheck(directoryState, strictDirectories),
-        buildSettingsValuesHealthCheck(settingWarnings),
+        buildSettingsValuesHealthCheck(settingWarnings, statusRoleDiagnostics),
         telemetryCheck.check,
         extensionCheck.check,
         buildStorageHealthCheck(items, settings, historySummary, authorAttribution, staleInProgress.scan, provenanceResolverOutcomes, provenanceInvalidValues),
@@ -2298,4 +2309,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=3c68e4be-fd09-560c-9654-f270e5d7ba73
+//# debugId=76693c03-9395-5bbf-bcc8-fa15e408f30f

package/dist/sdk/governance/status-role-diagnostics.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module sdk/governance/status-role-diagnostics
+ *
+ * Diagnoses lifecycle statuses that cannot participate in role-derived project
+ * management views because they have no registered lifecycle role.
+ */
+import type { ItemMetadata } from "../../types/index.js";
+import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
+/** Bounded evidence describing roleless status definitions and affected items. */
+export interface StatusRoleDiagnostics {
+    /** Total number of registered status ids that have no lifecycle role. */
+    roleless_status_count: number;
+    /** Registered status ids that have no lifecycle role. */
+    roleless_statuses: string[];
+    /** Whether roleless status ids were omitted from the bounded sample. */
+    roleless_statuses_truncated: boolean;
+    /** Number of items whose status resolves to a roleless definition. */
+    affected_item_count: number;
+    /** Bounded, deterministic sample of affected item ids. */
+    affected_item_ids: string[];
+    /** Whether affected item ids were omitted from the bounded sample. */
+    affected_item_ids_truncated: boolean;
+}
+/** Inspect role registration and affected items without mutating the tracker. */
+export declare function inspectStatusRoleAssignments(statusRegistry: RuntimeStatusRegistry, items: readonly ItemMetadata[], itemLimit?: number): StatusRoleDiagnostics;
+/** Convert role diagnostics into the stable health/validate warning token. */
+export declare function buildStatusRoleWarnings(diagnostics: StatusRoleDiagnostics): string[];

package/dist/sdk/governance/status-role-diagnostics.js

@@ -0,0 +1,36 @@
+
+!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]="cd7acf28-cb93-516e-9058-54c32625ec26")}catch(e){}}();
+import { normalizeStatusInputWithRegistry, } from "../../core/schema/runtime-schema.js";
+/** Inspect role registration and affected items without mutating the tracker. */
+export function inspectStatusRoleAssignments(statusRegistry, items, itemLimit = 25) {
+    const rolelessStatuses = statusRegistry.definitions
+        .filter((definition) => definition.roles.length === 0)
+        .map((definition) => definition.id)
+        .sort((left, right) => left.localeCompare(right));
+    const rolelessSet = new Set(rolelessStatuses);
+    const affectedItemIds = items
+        .filter((item) => {
+        const resolved = normalizeStatusInputWithRegistry(item.status, statusRegistry);
+        return resolved !== undefined && rolelessSet.has(resolved);
+    })
+        .map((item) => item.id)
+        .sort((left, right) => left.localeCompare(right));
+    return {
+        roleless_status_count: rolelessStatuses.length,
+        roleless_statuses: rolelessStatuses.slice(0, itemLimit),
+        roleless_statuses_truncated: rolelessStatuses.length > itemLimit,
+        affected_item_count: affectedItemIds.length,
+        affected_item_ids: affectedItemIds.slice(0, itemLimit),
+        affected_item_ids_truncated: affectedItemIds.length > itemLimit,
+    };
+}
+/** Convert role diagnostics into the stable health/validate warning token. */
+export function buildStatusRoleWarnings(diagnostics) {
+    return diagnostics.roleless_status_count === 0
+        ? []
+        : [
+            `schema_status_missing_lifecycle_role:${diagnostics.roleless_status_count}`,
+        ];
+}
+//# sourceMappingURL=status-role-diagnostics.js.map
+//# debugId=cd7acf28-cb93-516e-9058-54c32625ec26

package/dist/sdk/governance/validate-normalization.d.ts

@@ -0,0 +1,6 @@
+/** Normalize a repository-relative path to stable forward-slash form. */
+export declare function normalizeRelativePath(value: string): string;
+/** Normalize a repository-relative directory without trailing separators. */
+export declare function normalizeRelativeDirectoryPath(value: string): string;
+/** Treat blank and legacy null-like metadata tokens as absent values. */
+export declare function toMeaningfulString(value: unknown): string | undefined;

package/dist/sdk/governance/validate-normalization.js

@@ -0,0 +1,37 @@
+/**
+ * @module sdk/governance/validate-normalization
+ *
+ * Provides shared path and meaningful-value normalization for validation
+ * diagnostics without coupling the helpers to the command orchestration.
+ */
+
+!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]="de2cc648-965a-59c9-b688-0fe12edeec82")}catch(e){}}();
+import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
+/** Normalize a repository-relative path to stable forward-slash form. */
+export function normalizeRelativePath(value) {
+    return value
+        .replaceAll("\\", "/")
+        .replace(/^\.\/+/, "")
+        .replace(/^\/+/, "");
+}
+/** Normalize a repository-relative directory without trailing separators. */
+export function normalizeRelativeDirectoryPath(value) {
+    return normalizeRelativePath(value).replace(/\/+$/, "");
+}
+/** Treat blank and legacy null-like metadata tokens as absent values. */
+export function toMeaningfulString(value) {
+    const normalized = toNonEmptyStringOrUndefined(value);
+    if (!normalized) {
+        return undefined;
+    }
+    const lowered = normalized.toLowerCase();
+    if (lowered === "none" ||
+        lowered === "null" ||
+        lowered === "n/a" ||
+        lowered === "na") {
+        return undefined;
+    }
+    return normalized;
+}
+//# sourceMappingURL=validate-normalization.js.map
+//# debugId=de2cc648-965a-59c9-b688-0fe12edeec82

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

@@ -8,6 +8,7 @@ import { type OutputProjectionDeclaration } from "../output-projection.js";
 import { type RelationshipKindRegistry } from "../relationships.js";
 import { type ValidateItem } from "./validate-item-reader.js";
 import { buildLifecycleParentGraph, detectLifecycleParentCycles, resolveLifecycleDependencyCycleSamplePath } from "./hierarchy-validation.js";
+import { toMeaningfulString } from "./validate-normalization.js";
 type ValidateCheckName = "metadata" | "resolution" | "lifecycle" | "dependency_references" | "files" | "command_references" | "history_drift" | "format_version" | "storage_integrity";
 type ValidateStatus = "ok" | "warn" | "error";
 type ValidateDependencyCycleSeverity = "off" | "warn" | "error";
@@ -153,7 +154,6 @@ export interface ValidateCountsResult extends Omit<ValidateResult, "fixes"> {
  * totals, statuses, and truncation markers are preserved.
  */
 export declare function projectValidateCounts(result: ValidateResult): ValidateCountsResult;
-declare function toMeaningfulString(value: unknown): string | undefined;
 interface ValidateMetadataPolicy {
     profile: ValidateMetadataProfile;
     profile_source: "default" | "settings" | "option";

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="e7a231e7-0546-5d5f-b0c8-59629ad4d731")}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]="cde10e58-cfeb-5718-a471-3e4acf46cfe7")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -46,6 +46,8 @@ import { resolveLinkedTestSourceRef, resolveLinkedTestSourceWorkspaceRoot, resol
 import { readValidateItems, } from "./validate-item-reader.js";
 import { buildValidateHistoryDriftCheck } from "./validate-history-drift.js";
 import { buildLifecycleParentGraph, detectLifecycleParentCycles, resolveLifecycleDependencyCycleSamplePath, } from "./hierarchy-validation.js";
+import { buildStatusRoleWarnings, inspectStatusRoleAssignments, } from "./status-role-diagnostics.js";
+import { normalizeRelativeDirectoryPath, normalizeRelativePath, toMeaningfulString, } from "./validate-normalization.js";
 const FILE_SCAN_DIRECTORIES = ["src", "tests", "docs"];
 const FILE_SCAN_ROOT_FILES = [
     "README.md",
@@ -205,30 +207,6 @@ export function projectValidateCounts(result) {
             : {}),
     };
 }
-function normalizeRelativePath(value) {
-    return value
-        .replaceAll("\\", "/")
-        .replace(/^\.\/+/, "")
-        .replace(/^\/+/, "");
-}
-function normalizeRelativeDirectoryPath(value) {
-    const normalized = normalizeRelativePath(value);
-    return normalized.replace(/\/+$/, "");
-}
-function toMeaningfulString(value) {
-    const normalized = toNonEmptyStringOrUndefined(value);
-    if (!normalized) {
-        return undefined;
-    }
-    const lowered = normalized.toLowerCase();
-    if (lowered === "none" ||
-        lowered === "null" ||
-        lowered === "n/a" ||
-        lowered === "na") {
-        return undefined;
-    }
-    return normalized;
-}
 /* c8 ignore start -- runtime-status alias normalization is covered by status-registry integration tests */
 function normalizeStatusForRegistry(status, statusRegistry) {
     return normalizeStatusInput(status, statusRegistry) ?? status;
@@ -1484,15 +1462,21 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
     sortLifecycleScanRows(rows);
     const dependencyCycleDiagnostics = detectLifecycleDependencyCycles(rows.activeItems, idPrefix);
     const parentCycleDiagnostics = detectLifecycleParentCycles(items, statusRegistry);
-    const warnings = buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSeverity, parentCycleSeverity, {
-        dependencyCycles: dependencyCycleDiagnostics.cycle_count,
-        activeHierarchyCycles: parentCycleDiagnostics.active_cycle_count,
-        activeHierarchyCardinality: parentCycleDiagnostics.active_cardinality_violation_count,
-        activeHierarchyDivergence: parentCycleDiagnostics.active_parent_divergence_count,
-        legacyHierarchyCycles: parentCycleDiagnostics.legacy_cycle_count,
-        legacyHierarchyCardinality: parentCycleDiagnostics.legacy_cardinality_violation_count,
-        legacyHierarchyDivergence: parentCycleDiagnostics.legacy_parent_divergence_count,
-    });
+    const statusRoleDiagnostics = inspectStatusRoleAssignments(statusRegistry, items, verboseDiagnostics
+        ? Number.POSITIVE_INFINITY
+        : DIAGNOSTIC_LIST_SUMMARY_LIMIT);
+    const warnings = [
+        ...buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSeverity, parentCycleSeverity, {
+            dependencyCycles: dependencyCycleDiagnostics.cycle_count,
+            activeHierarchyCycles: parentCycleDiagnostics.active_cycle_count,
+            activeHierarchyCardinality: parentCycleDiagnostics.active_cardinality_violation_count,
+            activeHierarchyDivergence: parentCycleDiagnostics.active_parent_divergence_count,
+            legacyHierarchyCycles: parentCycleDiagnostics.legacy_cycle_count,
+            legacyHierarchyCardinality: parentCycleDiagnostics.legacy_cardinality_violation_count,
+            legacyHierarchyDivergence: parentCycleDiagnostics.legacy_parent_divergence_count,
+        }),
+        ...buildStatusRoleWarnings(statusRoleDiagnostics),
+    ];
     const diagnosticLimit = verboseDiagnostics
         ? Number.POSITIVE_INFINITY
         : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
@@ -1522,6 +1506,7 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
             ok: !hasErrorSeverityCycle && warnings.length === 0,
             details: {
                 checked_active_items: rows.activeItems.length,
+                lifecycle_status_roles: statusRoleDiagnostics,
                 active_closure_like_metadata_items: rows.closureLikeRows.length,
                 active_closure_like_metadata_rows: summarizedClosureLikeRows.values,
                 active_closure_like_metadata_rows_truncated: summarizedClosureLikeRows.truncated,
@@ -2288,4 +2273,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=e7a231e7-0546-5d5f-b0c8-59629ad4d731
+//# debugId=cde10e58-cfeb-5718-a471-3e4acf46cfe7

package/dist/sdk/governance/workspace-position.d.ts

@@ -0,0 +1,69 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type MergeDriverConfigurationAuditResult, type MergeFenceAuditResult } from "../merge/install.js";
+/** Stable readiness classifications returned by the workspace-position read. */
+export type WorkspacePositionState = "ready" | "merge_evidence_invalid" | "history_evidence_invalid" | "merge_reconciliation_required" | "history_repair_required" | "merge_fence_unprepared";
+/** One deterministic recovery action selected from aggregate workspace evidence. */
+export interface WorkspacePositionNextAction {
+    /** Executable pm command, or null when the workspace is ready. */
+    command: string | null;
+    /** Stable reason code explaining why this action takes precedence. */
+    reason: WorkspacePositionState;
+}
+/** Bounded SDK result shared by CLI, MCP, and package consumers. */
+export interface WorkspacePositionResult {
+    /** Whether all readiness evidence is clean. */
+    ok: boolean;
+    /** Highest-priority workspace readiness classification. */
+    state: WorkspacePositionState;
+    /** Committed merge-fence and clone-local driver evidence. */
+    merge_fence: {
+        committed: MergeFenceAuditResult;
+        clone_local_drivers: MergeDriverConfigurationAuditResult | null;
+    };
+    /** Bounded pending receipt evidence without private merge values. */
+    merge_receipts: {
+        pending_decision_count: number;
+        pending_item_ids: string[];
+        pending_item_ids_truncated: boolean;
+        lossless_count: number;
+        invalid_evidence_count: number;
+    };
+    /** Bounded append-only history drift evidence. */
+    history_drift: {
+        /** Whether the required history-drift evidence has its expected shape. */
+        evidence_valid: boolean;
+        drifted_item_count: number;
+        drifted_item_ids: string[];
+        drifted_item_ids_truncated: boolean;
+        counts: Record<string, unknown>;
+    };
+    /** One deterministic next action, avoiding multi-command guesswork. */
+    next_action: WorkspacePositionNextAction;
+    /** Non-fatal read warnings retained from the authoritative item scan. */
+    warnings: string[];
+    /** ISO timestamp for this aggregate read. */
+    generated_at: string;
+}
+declare function selectWorkspacePositionState(params: {
+    invalidEvidenceCount: number;
+    pendingDecisionCount: number;
+    losslessCount: number;
+    historyEvidenceValid: boolean;
+    driftedItemCount: number;
+    fence: MergeFenceAuditResult;
+    drivers: MergeDriverConfigurationAuditResult | null;
+}): WorkspacePositionState;
+declare function commandForWorkspacePositionState(state: WorkspacePositionState, pmRoot: string, platform?: NodeJS.Platform): string | null;
+/** Normalize defensive history-check evidence into the bounded position shape. */
+declare function normalizeWorkspaceHistoryDrift(details: Record<string, unknown>): WorkspacePositionResult["history_drift"];
+/** Read aggregate workspace position without flags, session state, or mutation. */
+export declare function readWorkspacePosition(global: GlobalOptions): Promise<WorkspacePositionResult>;
+/** Render the bounded workspace position for human CLI output. */
+export declare function formatWorkspacePositionHuman(result: WorkspacePositionResult): string;
+/** Public contract for focused unit verification. */
+export declare const _testOnlyWorkspacePosition: {
+    commandForWorkspacePositionState: typeof commandForWorkspacePositionState;
+    normalizeWorkspaceHistoryDrift: typeof normalizeWorkspaceHistoryDrift;
+    selectWorkspacePositionState: typeof selectWorkspacePositionState;
+};
+export {};

package/dist/sdk/governance/workspace-position.js

@@ -0,0 +1,164 @@
+/**
+ * @module sdk/governance/workspace-position
+ *
+ * Produces one bounded, read-only workspace readiness answer from merge-fence,
+ * merge-receipt, and append-only history evidence.
+ */
+
+!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]="e900c117-6d8d-55d3-86df-f543dc499930")}catch(e){}}();
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { nowIso } from "../../core/shared/time.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { renderPmCommand } from "../command-line.js";
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { auditMergeAttributeFence, auditMergeDriverConfiguration, findGitWorkspaceRoot, resolveProjectMergeTypeFolders, } from "../merge/install.js";
+import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
+import { buildValidateHistoryDriftCheck } from "./validate-history-drift.js";
+import { readValidateItems } from "./validate-item-reader.js";
+function selectWorkspacePositionState(params) {
+    if (params.invalidEvidenceCount > 0)
+        return "merge_evidence_invalid";
+    if (!params.historyEvidenceValid)
+        return "history_evidence_invalid";
+    if (params.pendingDecisionCount > 0 || params.losslessCount > 0) {
+        return "merge_reconciliation_required";
+    }
+    if (params.driftedItemCount > 0)
+        return "history_repair_required";
+    if (params.fence.status !== "ok" ||
+        params.drivers === null ||
+        params.drivers.status !== "ok") {
+        return "merge_fence_unprepared";
+    }
+    return "ready";
+}
+function commandForWorkspacePositionState(state, pmRoot, platform = process.platform) {
+    const commandArgs = ["--pm-path", pmRoot];
+    if (state === "merge_evidence_invalid")
+        return renderPmCommand([...commandArgs, "merge", "report"], platform);
+    if (state === "history_evidence_invalid") {
+        return renderPmCommand([...commandArgs, "validate", "--check-history-drift", "--full"], platform);
+    }
+    if (state === "merge_reconciliation_required") {
+        return renderPmCommand([...commandArgs, "merge", "reconcile"], platform);
+    }
+    if (state === "history_repair_required") {
+        return renderPmCommand([...commandArgs, "history-repair", "--all"], platform);
+    }
+    if (state === "merge_fence_unprepared") {
+        return renderPmCommand([...commandArgs, "merge", "install"], platform);
+    }
+    return null;
+}
+/** Normalize defensive history-check evidence into the bounded position shape. */
+function normalizeWorkspaceHistoryDrift(details) {
+    const driftedItemIds = Array.isArray(details.drifted_items)
+        ? details.drifted_items.filter((entry) => typeof entry === "string")
+        : [];
+    const evidenceValid = Array.isArray(details.drifted_items) &&
+        details.drifted_items.every((entry) => typeof entry === "string") &&
+        typeof details.drifted_items_count === "number" &&
+        Number.isInteger(details.drifted_items_count) &&
+        details.drifted_items_count >= 0 &&
+        typeof details.drifted_items_truncated === "boolean" &&
+        typeof details.counts === "object" &&
+        details.counts !== null &&
+        !Array.isArray(details.counts);
+    return {
+        evidence_valid: evidenceValid,
+        drifted_item_count: typeof details.drifted_items_count === "number"
+            ? details.drifted_items_count
+            : driftedItemIds.length,
+        drifted_item_ids: driftedItemIds,
+        drifted_item_ids_truncated: details.drifted_items_truncated === true,
+        counts: typeof details.counts === "object" && details.counts !== null
+            ? details.counts
+            : {},
+    };
+}
+/** Read aggregate workspace position without flags, session state, or mutation. */
+export async function readWorkspacePosition(global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await assertInitializedTracker(pmRoot);
+    const settings = await readSettings(pmRoot);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const itemReadWarnings = [];
+    const items = await readValidateItems({
+        includeBody: true,
+        pmRoot,
+        settings,
+        typeToFolder: typeRegistry.type_to_folder,
+        warnings: itemReadWarnings,
+    });
+    const gitWorkspaceRoot = await findGitWorkspaceRoot(pmRoot);
+    const [fence, drivers, receiptEvidence, drift] = await Promise.all([
+        auditMergeAttributeFence(pmRoot, resolveProjectMergeTypeFolders(settings)),
+        gitWorkspaceRoot === null
+            ? Promise.resolve(null)
+            : auditMergeDriverConfiguration(gitWorkspaceRoot),
+        inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+            includeLossless: true,
+            pmRoot,
+        }),
+        buildValidateHistoryDriftCheck(pmRoot, items, false),
+    ]);
+    const { pendingDecisions, lossless } = partitionMergeReceipts(receiptEvidence.receipts);
+    const pendingItemIds = [
+        ...new Set(pendingDecisions.map((receipt) => receipt.item_id)),
+    ].sort((left, right) => left.localeCompare(right));
+    const driftDetails = drift.check.details;
+    const historyDrift = normalizeWorkspaceHistoryDrift(driftDetails);
+    const state = selectWorkspacePositionState({
+        invalidEvidenceCount: receiptEvidence.invalid_evidence_count,
+        pendingDecisionCount: pendingDecisions.length,
+        losslessCount: lossless.length,
+        historyEvidenceValid: historyDrift.evidence_valid,
+        driftedItemCount: historyDrift.drifted_item_count,
+        fence,
+        drivers,
+    });
+    return {
+        ok: state === "ready",
+        state,
+        merge_fence: {
+            committed: fence,
+            clone_local_drivers: drivers,
+        },
+        merge_receipts: {
+            pending_decision_count: pendingDecisions.length,
+            pending_item_ids: pendingItemIds.slice(0, 25),
+            pending_item_ids_truncated: pendingItemIds.length > 25,
+            lossless_count: lossless.length,
+            invalid_evidence_count: receiptEvidence.invalid_evidence_count,
+        },
+        history_drift: historyDrift,
+        next_action: {
+            command: commandForWorkspacePositionState(state, pmRoot),
+            reason: state,
+        },
+        warnings: [...new Set(itemReadWarnings)].sort((left, right) => left.localeCompare(right)),
+        generated_at: nowIso(),
+    };
+}
+/** Render the bounded workspace position for human CLI output. */
+export function formatWorkspacePositionHuman(result) {
+    const action = result.next_action.command ?? "none";
+    return [
+        `workspace_position: ${result.state}`,
+        `merge_fence: ${result.merge_fence.committed.status}`,
+        `clone_local_drivers: ${result.merge_fence.clone_local_drivers?.status ?? "unavailable"}`,
+        `pending_merge_decisions: ${result.merge_receipts.pending_decision_count}`,
+        `history_drifted_items: ${result.history_drift.drifted_item_count}`,
+        `next_action: ${action}`,
+    ].join("\n");
+}
+/** Public contract for focused unit verification. */
+export const _testOnlyWorkspacePosition = {
+    commandForWorkspacePositionState,
+    normalizeWorkspaceHistoryDrift,
+    selectWorkspacePositionState,
+};
+//# sourceMappingURL=workspace-position.js.map
+//# debugId=e900c117-6d8d-55d3-86df-f543dc499930

package/dist/sdk/governance.d.ts

@@ -16,6 +16,8 @@ export * from "./governance/defect-recurrence.js";
 export { runReindex, type ReindexOptions, type ReindexResult, } from "./governance/reindex.js";
 export * from "./governance/stale-work.js";
 export * from "./governance/storage-integrity.js";
+export * from "./governance/status-role-diagnostics.js";
+export * from "./governance/workspace-position.js";
 export { runUpgrade, type UpgradeCliResult, type UpgradeCommandOptions, type UpgradeCommandRunner, type UpgradeCommandRunnerResult, type UpgradePackageResult, type UpgradeResult, } from "./governance/upgrade.js";
 export * from "./governance/validate.js";
 export * from "./author-attribution.js";

package/dist/sdk/governance.js

@@ -4,7 +4,7 @@
  * Provides validation, health, integrity, and mutation-policy primitives.
  */
 
-!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]="c2063b82-58b6-54c9-baff-ca252cadf463")}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]="ff251826-36f0-5b92-bee8-ca71d265986c")}catch(e){}}();
 export * from "./governance/gc.js";
 export * from "./governance/health.js";
 export * from "./governance/extension-host-version.js";
@@ -18,6 +18,8 @@ export * from "./governance/defect-recurrence.js";
 export { runReindex, } from "./governance/reindex.js";
 export * from "./governance/stale-work.js";
 export * from "./governance/storage-integrity.js";
+export * from "./governance/status-role-diagnostics.js";
+export * from "./governance/workspace-position.js";
 export { runUpgrade, } from "./governance/upgrade.js";
 export * from "./governance/validate.js";
 export * from "./author-attribution.js";
@@ -25,4 +27,4 @@ export * from "./mutation-guard.js";
 export * from "./governance/provenance-health.js";
 export * from "./similarity.js";
 //# sourceMappingURL=governance.js.map
-//# debugId=c2063b82-58b6-54c9-baff-ca252cadf463
+//# debugId=ff251826-36f0-5b92-bee8-ca71d265986c

package/dist/sdk/history-read.js

@@ -7,13 +7,13 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="aca866d3-32b9-5212-bb4b-f1484e41bb27")}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]="f1ea4209-59d4-53f0-a8ea-2e060e385d14")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
-import { hashDocument, hashEmptyDocument, } from "../core/history/history.js";
-import { replayToCanonicalItemDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { hashDocument, hashDocumentVerificationCandidates, hashEmptyDocument, } from "../core/history/history.js";
+import { replayToCanonicalItemDocument, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -28,11 +28,19 @@ import { resolveHistorySubject } from "./history-redact.js";
  * document to compare.
  */
 export function verifyHistoryEntries(history, currentDocument) {
-    const verification = verifyHistoryChain(history);
+    const verification = verifyHistoryChainWithVersion(history);
     const latestAfterHash = history.length > 0
         ? history[history.length - 1].after_hash
         : hashEmptyDocument();
-    const currentItemHash = currentDocument === undefined ? undefined : hashDocument(currentDocument);
+    const currentItemHashCandidates = currentDocument === undefined ||
+        verification.item_hash_version === undefined
+        ? undefined
+        : hashDocumentVerificationCandidates(currentDocument, verification.item_hash_version);
+    const currentItemHash = currentDocument === undefined
+        ? undefined
+        : currentItemHashCandidates === undefined
+            ? hashDocument(currentDocument)
+            : currentItemHashCandidates[Math.max(0, currentItemHashCandidates.indexOf(latestAfterHash))];
     const currentMatchesLatest = currentItemHash === undefined
         ? undefined
         : currentItemHash === latestAfterHash;
@@ -83,4 +91,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=aca866d3-32b9-5212-bb4b-f1484e41bb27
+//# debugId=f1ea4209-59d4-53f0-a8ea-2e060e385d14