@unbrained/pm-cli 2026.8.21 → 2026.8.23

package/dist/sdk/extension/output-ownership.js

@@ -4,7 +4,7 @@
  * Classifies output overrides against manifest-declared command ownership.
  */
 
-!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]="0dc7b063-dc72-595f-8e40-8a06f9db69e1")}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]="e5a4cea9-ac5d-5bda-9f7c-6cf8cf9e9998")}catch(e){}}();
 import { normalizeExtensionNameForMatch } from "./shared.js";
 /** Collect doctor warnings for output overrides without an explicit command or result ownership boundary. */
 export function collectGlobalOutputOverrideDoctorWarnings(activationResult, loadResult) {
@@ -13,6 +13,7 @@ export function collectGlobalOutputOverrideDoctorWarnings(activationResult, load
         : []));
     const serviceWarnings = activationResult.services.overrides
         .filter((entry) => entry.service === "output_format")
+        .filter((entry) => entry.passThrough !== true)
         .filter((entry) => !commandScopedOwners.has(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`))
         .map((entry) => `extension_output_service_override_global:${entry.service}:${entry.layer}:${entry.name}`);
     const rendererWarnings = activationResult.renderers.overrides
@@ -22,4 +23,4 @@ export function collectGlobalOutputOverrideDoctorWarnings(activationResult, load
     return [...new Set([...serviceWarnings, ...rendererWarnings])].sort((left, right) => left.localeCompare(right));
 }
 //# sourceMappingURL=output-ownership.js.map
-//# debugId=0dc7b063-dc72-595f-8e40-8a06f9db69e1
+//# debugId=e5a4cea9-ac5d-5bda-9f7c-6cf8cf9e9998

package/dist/sdk/extension/scaffold.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!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]="30dfc6e4-27c5-56c0-981b-94e85b780f1f")}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]="5321d574-4de4-5f94-99db-0c49639673fc")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../../core/fs/fs-utils.js";
@@ -1483,6 +1483,12 @@ function buildDeclarativeCapabilityTestBlock(extensionName, commandName, capabil
                     "",
                     "  // The starter provider reads only document title/id, so `settings` is a minimal",
                     "  // typed stub and `documents` carry just the fields it inspects.",
+                    "  const settings = {",
+                    "    testing: {",
+                    "      record_results_to_items: false,",
+                    "      allow_untrusted_linked_tests: false,",
+                    "    },",
+                    "  } as PmSettings;",
                     "  const query = await ext.runSearchProvider({",
                     `    provider: ${JSON.stringify(searchProviderName)},`,
                     '    operation: "query",',
@@ -1491,7 +1497,7 @@ function buildDeclarativeCapabilityTestBlock(extensionName, commandName, capabil
                     '      mode: "semantic",',
                     '      tokens: ["sync"],',
                     "      options: {},",
-                    "      settings: {} as PmSettings,",
+                    "      settings,",
                     "      documents: [",
                     '        { metadata: { id: "pm-1", title: "Sync external context" }, body: "" },',
                     '        { metadata: { id: "pm-2", title: "Unrelated task" }, body: "" },',
@@ -1503,14 +1509,14 @@ function buildDeclarativeCapabilityTestBlock(extensionName, commandName, capabil
                     "  const embedding = await ext.runSearchProvider({",
                     `    provider: ${JSON.stringify(searchProviderName)},`,
                     '    operation: "embed",',
-                    '    context: { input: "abc", settings: {} as PmSettings, model: "starter-model" },',
+                    '    context: { input: "abc", settings, model: "starter-model" },',
                     "  });",
                     "  assert.deepEqual(embedding, [3]);",
                     "",
                     "  const vectorHits = await ext.runVectorStoreAdapter({",
                     `    adapter: ${JSON.stringify(vectorAdapterName)},`,
                     '    operation: "query",',
-                    "    context: { vector: [0.1, 0.2], limit: 2, settings: {} as PmSettings },",
+                    "    context: { vector: [0.1, 0.2], limit: 2, settings },",
                     "  });",
                     '  assert.deepEqual(vectorHits, [{ id: "starter-vector-hit", score: 2 }]);',
                 ]),
@@ -2300,4 +2306,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=30dfc6e4-27c5-56c0-981b-94e85b780f1f
+//# debugId=5321d574-4de4-5f94-99db-0c49639673fc

package/dist/sdk/flag-invocation-contracts.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]="0f857893-8441-54ad-af99-abaae9af864d")}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]="32dca84c-9a21-570c-a0e0-0f0356c84c0d")}catch(e){}}();
 const FLAG_DESCRIPTIONS = Object.freeze({
     "--body": "Set the item body.",
     "--body-file": "Read the item body from a file.",
@@ -68,6 +68,7 @@ const BOOLEAN_FLAG_NAMES = new Set([
     "--all-affected-ids",
     "--all-day",
     "--all-streams",
+    "--acknowledge-linked-tests",
     "--append-stable",
     "--auto-fix",
     "--auto-pm-context",
@@ -133,6 +134,7 @@ const BOOLEAN_FLAG_NAMES = new Set([
     "--only-last",
     "--output-row-contract",
     "--override-linked-pm-context",
+    "--override-linked-workspace-context",
     "--packages-only",
     "--past",
     "--phrase-exact",
@@ -315,4 +317,4 @@ export function verifyCliFlagInvocationParity(command, declarations, observation
     };
 }
 //# sourceMappingURL=flag-invocation-contracts.js.map
-//# debugId=0f857893-8441-54ad-af99-abaae9af864d
+//# debugId=32dca84c-9a21-570c-a0e0-0f0356c84c0d

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="4959a1ef-29e6-50ae-aaf8-fe078001bff6")}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]="30cf6de5-af9b-54a1-b376-1c9e5d543ae1")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -962,6 +962,42 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "github_source_entry_unbuilt",
         aliases: [],
     },
+    {
+        code: "hierarchy_cardinality_created",
+        meaning: "Hierarchy cardinality created condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/graph/hierarchy-integrity.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "hierarchy_cardinality_created",
+        aliases: [],
+    },
+    {
+        code: "hierarchy_cycle_created",
+        meaning: "Hierarchy cycle created condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/graph/hierarchy-integrity.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "hierarchy_cycle_created",
+        aliases: [],
+    },
+    {
+        code: "hierarchy_parent_divergence_created",
+        meaning: "Hierarchy parent divergence created condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/graph/hierarchy-integrity.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "hierarchy_parent_divergence_created",
+        aliases: [],
+    },
     {
         code: "history_author_acknowledge_plan_conflict",
         meaning: "History author acknowledge plan conflict condition.",
@@ -1620,6 +1656,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "invalid_read_output_session",
         aliases: [],
     },
+    {
+        code: "invalid_reproducible_process_environment",
+        meaning: "Invalid reproducible process environment condition.",
+        stability: "provisional",
+        exit_code: 2,
+        class: "usage",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/reproducibility/process.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "invalid_reproducible_process_environment",
+        aliases: [],
+    },
     {
         code: "invalid_workspace_snapshot_target",
         meaning: "Invalid workspace snapshot target condition.",
@@ -1944,6 +1992,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "missing_cli_flag",
         aliases: [],
     },
+    {
+        code: "missing_destination",
+        meaning: "Missing destination condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/grammar-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_destination",
+        aliases: [],
+    },
+    {
+        code: "missing_directory",
+        meaning: "Missing directory condition.",
+        stability: "stable",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_directory",
+        aliases: [],
+    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=4959a1ef-29e6-50ae-aaf8-fe078001bff6
+//# debugId=30cf6de5-af9b-54a1-b376-1c9e5d543ae1

package/dist/sdk/generated/generated-error-code-catalog-part-2.js

@@ -1,31 +1,7 @@
 /** Generated partition 2 of the exhaustive error-code catalog. */
 
-!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]="d7f4f4f0-d044-5216-b2c4-d76b4d8854a9")}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]="9b6149b0-ca3e-5093-aba5-43385d3368f7")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_2 = [
-    {
-        code: "missing_destination",
-        meaning: "Missing destination condition.",
-        stability: "provisional",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["sdk/cli-contracts/grammar-contracts.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_destination",
-        aliases: [],
-    },
-    {
-        code: "missing_directory",
-        meaning: "Missing directory condition.",
-        stability: "stable",
-        exit_code: 1,
-        class: "generic_failure",
-        recovery: "Inspect the structured error guidance and retry the suggested command.",
-        sources: ["core/diagnostics/remediation.ts"],
-        emitting_commands: ["*"],
-        canonical_code: "missing_directory",
-        aliases: [],
-    },
     {
         code: "missing_init_recovery",
         meaning: "Missing init recovery condition.",
@@ -110,6 +86,7 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
             "cli/main.ts",
             "cli/register-mutation.ts",
             "core/telemetry/observability.ts",
+            "sdk/governance/assurance-action.ts",
             "sdk/history-redact.ts",
             "sdk/invocation-author.ts",
         ],
@@ -531,6 +508,78 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "redundant_edge",
         aliases: [],
     },
+    {
+        code: "refusal_allowed_values_mismatch",
+        meaning: "Refusal allowed values mismatch condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "refusal_allowed_values_mismatch",
+        aliases: [],
+    },
+    {
+        code: "refusal_error_code_mismatch",
+        meaning: "Refusal error code mismatch condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "refusal_error_code_mismatch",
+        aliases: [],
+    },
+    {
+        code: "refusal_exit_code_mismatch",
+        meaning: "Refusal exit code mismatch condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "refusal_exit_code_mismatch",
+        aliases: [],
+    },
+    {
+        code: "refusal_mutated_state",
+        meaning: "Refusal mutated state condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "refusal_mutated_state",
+        aliases: [],
+    },
+    {
+        code: "refusal_probe_missing",
+        meaning: "Refusal probe missing condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "refusal_probe_missing",
+        aliases: [],
+    },
+    {
+        code: "refusal_recovery_failed",
+        meaning: "Refusal recovery failed condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "refusal_recovery_failed",
+        aliases: [],
+    },
     {
         code: "reindex_already_running",
         meaning: "Reindex already running condition.",
@@ -1099,6 +1148,18 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
         canonical_code: "undeclared_observation",
         aliases: [],
     },
+    {
+        code: "unexpected_refusal_probe",
+        meaning: "Unexpected refusal probe condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-corpus-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "unexpected_refusal_probe",
+        aliases: [],
+    },
     {
         code: "unknown_command",
         meaning: "Unknown command condition.",
@@ -1978,4 +2039,4 @@ export const PM_ERROR_CODE_CATALOG_PART_2 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-2.js.map
-//# debugId=d7f4f4f0-d044-5216-b2c4-d76b4d8854a9
+//# debugId=9b6149b0-ca3e-5093-aba5-43385d3368f7

package/dist/sdk/governance/assurance-action.js

@@ -4,7 +4,7 @@
  * Normalizes the assurance action vocabulary once for CLI, SDK, and MCP hosts.
  */
 
-!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]="57c12241-812d-5db6-9a07-ca256152b130")}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]="f66a964d-1352-5523-ab91-5177d0d93ce8")}catch(e){}}();
 import { createHash } from "node:crypto";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -18,6 +18,7 @@ import { resolvePmRoot } from "../runtime-primitives.js";
 import { parseRuntimeInteger, readRuntimeString } from "../runtime-input.js";
 import { analyzeDefectChangeRisk, buildDefectRecurrenceIndex, parseDefectChangeRiskRequest, } from "./defect-recurrence.js";
 import { defectRecurrenceItemSignals } from "./defect-recurrence-signals.js";
+import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
 let riskIndexCache;
 /** Assurance registry and evaluation verbs shared by every transport. */
 export const ASSURANCE_ACTIONS = [
@@ -43,17 +44,36 @@ function parseAction(value) {
     if (ASSURANCE_ACTIONS.includes(value)) {
         return value;
     }
-    throw new PmCliError(`Unknown assurance action ${value}. Expected: ${ASSURANCE_ACTIONS.join(", ")}`, EXIT_CODE.USAGE);
+    throw createUnknownSubcommandError({
+        command_path: "assurance",
+        token: value,
+        allowed: ASSURANCE_ACTIONS,
+        display_name: "assurance action",
+    });
+}
+/** Throw the shared structured usage refusal for a missing assurance operand. */
+function missingAssuranceArgument(operand, detail, example) {
+    throw new PmCliError(detail, EXIT_CODE.USAGE, {
+        code: "missing_required_argument",
+        required: `Provide the missing assurance operand: ${operand}.`,
+        examples: [example],
+        recovery: { missing: [operand] },
+    });
 }
 function parseKind(value) {
-    if (value &&
-        ASSURANCE_DECLARATION_KINDS.includes(value)) {
+    if (!value) {
+        return missingAssuranceArgument("kind", `Assurance declaration kind is required. Expected: ${ASSURANCE_DECLARATION_KINDS.join(", ")}`, "pm assurance list measurement");
+    }
+    if (ASSURANCE_DECLARATION_KINDS.includes(value)) {
         return value;
     }
     throw new PmCliError(`Assurance declaration kind is required. Expected: ${ASSURANCE_DECLARATION_KINDS.join(", ")}`, EXIT_CODE.USAGE);
 }
 function parsePreset(value) {
-    if (value && ASSURANCE_PRESET_IDS.includes(value)) {
+    if (!value) {
+        return missingAssuranceArgument("preset", `Assurance preset is required. Expected: ${ASSURANCE_PRESET_IDS.join(", ")}`, "pm assurance apply software-delivery --owner <pm-item-id>");
+    }
+    if (ASSURANCE_PRESET_IDS.includes(value)) {
         return value;
     }
     throw new PmCliError(`Assurance preset is required. Expected: ${ASSURANCE_PRESET_IDS.join(", ")}`, EXIT_CODE.USAGE);
@@ -61,7 +81,7 @@ function parsePreset(value) {
 function requireOwner(input) {
     if (input.owner?.trim())
         return input.owner.trim();
-    throw new PmCliError("assurance preset and derivation actions require --owner <pm-item-id>", EXIT_CODE.USAGE);
+    return missingAssuranceArgument("owner", "assurance preset and derivation actions require --owner <pm-item-id>", "pm assurance apply software-delivery --owner <pm-item-id>");
 }
 function parseDefinition(kind, value) {
     let parsed = value;
@@ -173,7 +193,7 @@ async function runAdoptionAction(action, input, pmRoot) {
         };
     }
     if (!input.id) {
-        throw new PmCliError("assurance promote requires an assertion id", EXIT_CODE.USAGE);
+        return missingAssuranceArgument("assertion-id", "assurance promote requires an assertion id", "pm assurance promote <assertion-id> --enforcement warn");
     }
     if (input.enforcement !== "warn" && input.enforcement !== "block") {
         throw new PmCliError("assurance promote requires --enforcement warn|block", EXIT_CODE.USAGE);
@@ -186,7 +206,7 @@ async function runAdoptionAction(action, input, pmRoot) {
 }
 async function runGateAction(input, pmRoot, runtime) {
     if (!input.id) {
-        throw new PmCliError("assurance run requires a gate id", EXIT_CODE.USAGE);
+        return missingAssuranceArgument("gate-id", "assurance run requires a gate id", "pm assurance run <gate-id> --trigger ci --dry-run");
     }
     const gateId = input.id;
     if (!input.trigger) {
@@ -320,7 +340,7 @@ export async function runAssuranceAction(input, global = {}, runtime = {}) {
     if (action === "list")
         return listAssuranceDeclarations(pmRoot, kind);
     if (!input.id) {
-        throw new PmCliError(`assurance ${action} requires an id`, EXIT_CODE.USAGE);
+        return missingAssuranceArgument("id", `assurance ${action} requires an id`, `pm assurance ${action} ${kind} <id>`);
     }
     const id = input.id;
     if (action === "show") {
@@ -377,4 +397,4 @@ export function runAssuranceDispatch(args, options, global) {
     }, global);
 }
 //# sourceMappingURL=assurance-action.js.map
-//# debugId=57c12241-812d-5db6-9a07-ca256152b130
+//# debugId=f66a964d-1352-5523-ab91-5177d0d93ce8

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

@@ -7,6 +7,7 @@ import { type HistoryAuthorAttributionScan } from "../author-attribution.js";
 import type { PmSettings } from "../../types/index.js";
 import { buildCapabilityContractMetadata, collectUnknownCapabilityGuidance } from "../extension/doctor.js";
 import { type StaleInProgressScan } from "./stale-work.js";
+import { type HierarchyIntegrityAnalysis } from "../graph/hierarchy-integrity.js";
 type HealthStatus = "ok" | "warn";
 type MigrationRuntimeStatus = "pending" | "failed" | "applied";
 /** Documents the health check payload exchanged by command, SDK, and package integrations. */
@@ -145,6 +146,7 @@ declare function normalizeExtensionNameForMatch(value: string): string;
 declare function isExpectedUnmanagedExtension(name: string, directory: string): boolean;
 declare function isDirectory(targetPath: string): Promise<boolean>;
 declare function listItemDocumentPaths(pmRoot: string, typeToFolder: Record<string, string>): Promise<string[]>;
+declare function buildHierarchyIntegrityWarnings(analysis: HierarchyIntegrityAnalysis): string[];
 declare function buildExtensionHealthTriageSummary(warnings: string[], loadFailureCount: number, activationFailureCount: number, migrationStatus: MigrationStatusSummary, managedStateWarningCount: number, managedExtensionEntriesCount: number, unmanagedLoadedExtensions: string[], unmanagedExpectedExtensions: string[], unmanagedActionRequiredExtensions: string[]): ExtensionHealthTriageSummary;
 declare function summarizeRecordList(value: unknown, limit: number): {
     count: number;
@@ -218,6 +220,7 @@ declare function projectHealthResult(result: HealthResult, options: RunHealthOpt
 export declare function runHealth(global: GlobalOptions, options?: RunHealthOptions): Promise<HealthResult>;
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlyHealthCommand: {
+    buildHierarchyIntegrityWarnings: typeof buildHierarchyIntegrityWarnings;
     buildExtensionHealthTriageSummary: typeof buildExtensionHealthTriageSummary;
     buildHealthFindings: typeof buildHealthFindings;
     buildCapabilityContractMetadata: typeof buildCapabilityContractMetadata;

package/dist/sdk/governance/health.js

@@ -4,11 +4,13 @@
  * 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]="a7e3a41b-7d69-526d-aa3e-bc244ef8fe0c")}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]="f7b3ff92-1fc7-55e9-aa76-af956714998f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { isTerminalStatus } from "../../core/item/status.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import { isFileMissingError, readFileIfExists, } from "../../core/fs/fs-utils.js";
 import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, runActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
@@ -44,6 +46,8 @@ import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
 import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.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;
@@ -61,6 +65,7 @@ const TELEMETRY_SERVER_MAX_SCHEMA_VERSION_HEADERS = [
 function isAdvisoryHealthWarning(warning, requireMergeDrivers = false) {
     return (warning.startsWith("telemetry_") ||
         warning.startsWith("history_stream_over_compact_threshold:") ||
+        warning.startsWith("integrity_legacy_hierarchy_") ||
         warning.startsWith("stale_in_progress_items:") ||
         warning.startsWith("provenance_resolver_zero_success:") ||
         warning.startsWith("provenance_value_domain_invalid:") ||
@@ -315,10 +320,25 @@ async function scanHistoryIntegrity(pmRoot) {
     }
     return { files, unreadable, conflictMarkers, invalidJson };
 }
-async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers) {
+function buildHierarchyIntegrityWarnings(analysis) {
+    return [
+        ...analysis.cycles.map((cycle) => cycle.legacy_terminal
+            ? `integrity_legacy_hierarchy_cycle:${cycle.item_ids.join(",")}`
+            : `integrity_hierarchy_cycle:${cycle.item_ids.join(",")}`),
+        ...analysis.cardinality_violations.map((finding) => finding.legacy_terminal
+            ? `integrity_legacy_hierarchy_cardinality:${finding.child_id}`
+            : `integrity_hierarchy_cardinality:${finding.child_id}`),
+        ...analysis.divergences.map((finding) => finding.legacy_terminal
+            ? `integrity_legacy_hierarchy_divergence:${finding.child_id}`
+            : `integrity_hierarchy_divergence:${finding.child_id}`),
+    ];
+}
+async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers, items) {
     const itemScan = await scanItemIntegrity(pmRoot, typeToFolder, schema);
     const historyScan = await scanHistoryIntegrity(pmRoot);
     const formatVersionScan = scanItemFormatVersions(itemScan.formatVersions);
+    const statusRegistry = resolveRuntimeStatusRegistry(schema);
+    const hierarchyIntegrity = analyzeHierarchyIntegrity(items, (status) => isTerminalStatus(status, statusRegistry), resolveWorkspaceRelationshipKindRegistry());
     const trackedRuntimeCache = await scanTrackedRuntimeCache(pmRoot);
     const gitWorkspaceRoot = await findGitWorkspaceRoot(pmRoot);
     const mergeDriverAudit = gitWorkspaceRoot === null
@@ -345,6 +365,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ...formatVersionScan.outdated.map((entry) => `integrity_item_outdated_format_version:${entry}`),
         /* c8 ignore stop */
         ...formatVersionScan.ahead.map((entry) => `integrity_item_ahead_format_version:${entry}`),
+        ...buildHierarchyIntegrityWarnings(hierarchyIntegrity),
         ...(trackedRuntimeCache.tracked_path_count > 0
             ? [
                 `tracked_runtime_cache_files:${trackedRuntimeCache.tracked_path_count}`,
@@ -360,11 +381,12 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
             : []),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+    const actionableWarnings = normalizedWarnings.filter((warning) => !warning.startsWith("integrity_legacy_hierarchy_"));
     return {
         check: {
             name: "integrity",
-            status: normalizedWarnings.length === 0 ? "ok" : "warn",
-            ok: normalizedWarnings.length === 0,
+            status: actionableWarnings.length === 0 ? "ok" : "warn",
+            ok: actionableWarnings.length === 0,
             details: {
                 checked_item_files: itemScan.paths.length,
                 checked_history_streams: historyScan.files.length,
@@ -377,6 +399,9 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                     history_invalid_json: historyScan.invalidJson.length,
                     item_outdated_format_version: formatVersionScan.outdated.length,
                     item_ahead_format_version: formatVersionScan.ahead.length,
+                    hierarchy_cycles: hierarchyIntegrity.cycles.length,
+                    hierarchy_cardinality_violations: hierarchyIntegrity.cardinality_violations.length,
+                    hierarchy_parent_divergences: hierarchyIntegrity.divergences.length,
                     tracked_runtime_cache_files: trackedRuntimeCache.tracked_path_count,
                     merge_driver_configuration: mergeDriverAudit === null || mergeDriverAudit.status === "ok"
                         ? 0
@@ -390,6 +415,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                 item_parse_failures: itemScan.parseFailures,
                 item_outdated_format_version: formatVersionScan.outdated,
                 item_ahead_format_version: formatVersionScan.ahead,
+                hierarchy_integrity: {
+                    ...hierarchyIntegrity,
+                    relations: summarizeRecordList(hierarchyIntegrity.relations, BRIEF_HEALTH_DETAIL_LIMIT),
+                },
                 history_unreadable: historyScan.unreadable,
                 history_conflict_markers: historyScan.conflictMarkers,
                 history_invalid_json: historyScan.invalidJson,
@@ -1832,7 +1861,9 @@ function extractHistoryDriftedCount(historyDriftCheck) {
 function buildHealthRemediationSources(params) {
     return {
         settings: params.normalizedSettingsReadWarnings,
-        directories: params.directoryState.missingDirs.map((dir) => `missing_directory:${dir}`).concat(params.directoryState.hookWarnings),
+        directories: params.directoryState.missingDirs
+            .map((dir) => `missing_directory:${dir}`)
+            .concat(params.directoryState.hookWarnings),
         settings_values: params.settingWarnings,
         telemetry: params.telemetryCheck.warnings,
         extensions: params.extensionCheck.warnings,
@@ -2000,7 +2031,7 @@ export async function runHealth(global, options = {}) {
     const locksCheck = await buildLocksCheck(pmRoot);
     const integrityCheck = skipPolicy.skipIntegrity
         ? buildSkippedHealthCheck("integrity")
-        : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema, options.requireMergeDrivers === true);
+        : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema, options.requireMergeDrivers === true, items);
     const historyDriftCheck = skipPolicy.skipDrift
         ? buildSkippedHealthCheck("history_drift")
         : await buildHistoryDriftCheck(pmRoot, itemsWithBody);
@@ -2082,6 +2113,7 @@ export async function runHealth(global, options = {}) {
 }
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
 export const _testOnlyHealthCommand = {
+    buildHierarchyIntegrityWarnings,
     buildExtensionHealthTriageSummary,
     buildHealthFindings,
     buildCapabilityContractMetadata,
@@ -2110,4 +2142,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=a7e3a41b-7d69-526d-aa3e-bc244ef8fe0c
+//# debugId=f7b3ff92-1fc7-55e9-aa76-af956714998f

package/dist/sdk/governance/hierarchy-validation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module sdk/governance/hierarchy-validation
+ *
+ * Adapts the shared hierarchy analyzer to validation-specific diagnostics and
+ * deterministic cycle paths without coupling the analyzer to CLI policy.
+ */
+import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
+import type { RelationshipKindRegistry } from "../relationships.js";
+import type { ValidateItem } from "./validate-item-reader.js";
+/** Resolve one deterministic closed walk through a known cycle component. */
+export declare function resolveLifecycleDependencyCycleSamplePath(component: string[], graph: Map<string, string[]>): string[];
+/** Build canonical child-to-parent adjacency across every hierarchy spelling. */
+export declare function buildLifecycleParentGraph(items: ValidateItem[], relationshipRegistry?: RelationshipKindRegistry): Map<string, string[]>;
+/** Project shared hierarchy analysis into the validation result contract. */
+export declare function detectLifecycleParentCycles(items: ValidateItem[], statusRegistry?: RuntimeStatusRegistry, relationshipRegistry?: RelationshipKindRegistry): {
+    cycle_count: number;
+    active_cycle_count: number;
+    legacy_cycle_count: number;
+    cycle_item_ids: string[];
+    cycle_sample_paths: string[];
+    cardinality_violation_count: number;
+    active_cardinality_violation_count: number;
+    legacy_cardinality_violation_count: number;
+    cardinality_violation_rows: string[];
+    parent_divergence_count: number;
+    active_parent_divergence_count: number;
+    legacy_parent_divergence_count: number;
+    parent_divergence_rows: string[];
+};