@unbrained/pm-cli 2026.8.19 → 2026.8.20

package/dist/core/shared/constants.d.ts

@@ -4,6 +4,7 @@
  * Provides shared primitives and utilities for Constants.
  */
 import type { BuiltinItemType, GovernancePreset, GovernanceSettings, PmSettings, RuntimeStatusDefinition, RuntimeWorkflowDefinition } from "../../types/index.js";
+export { ITEM_METADATA_KEY_ORDER, ITEM_PROJECT_CONTEXT_KEYS, } from "./item-metadata-contract.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
  *
@@ -28,10 +29,6 @@ export declare const PM_OPTIONAL_TYPE_SUBDIRS: readonly ["decisions", "events",
 export declare const PM_REQUIRED_SUBDIRS: readonly ["", "epics", "features", "tasks", "chores", "issues", "schema", "history", "search", "extensions", "locks", "decisions", "events", "reminders", "milestones", "meetings", "plans"];
 /** Public contract for type to folder, shared by SDK and presentation-layer consumers. */
 export declare const TYPE_TO_FOLDER: Record<BuiltinItemType, string>;
-/** Portable project-context fields shared by storage order and structured mutation IO. */
-export declare const ITEM_PROJECT_CONTEXT_KEYS: readonly ["goal", "objective", "value", "impact", "outcome", "why_now", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "unblock_note", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result"];
-/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
-export declare const ITEM_METADATA_KEY_ORDER: ReadonlyArray<string>;
 type BuiltinGovernancePreset = Exclude<GovernancePreset, "custom">;
 /** Public contract for governance preset defaults, shared by SDK and presentation-layer consumers. */
 export declare const GOVERNANCE_PRESET_DEFAULTS: Record<BuiltinGovernancePreset, Omit<GovernanceSettings, "preset">>;
@@ -67,4 +64,3 @@ export type TelemetryErrorCategory = "usage" | "validation" | "conflict" | "runt
 export declare const TELEMETRY_ERROR_CATEGORY_BY_CODE: Readonly<Record<string, TelemetryErrorCategory>>;
 /** Implements resolve telemetry error category for the public runtime surface of this module. */
 export declare function resolveTelemetryErrorCategory(errorCode: string | undefined): TelemetryErrorCategory;
-export {};

package/dist/core/shared/constants.js

@@ -1,6 +1,7 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="45e1dcb9-d2d6-52d7-b0b0-a57556a3fb03")}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]="70cce114-b8a7-5770-ae42-eec473515709")}catch(e){}}();
 import { createDefaultExtensionGovernancePolicy } from "../extensions/extension-types.js";
+export { ITEM_METADATA_KEY_ORDER, ITEM_PROJECT_CONTEXT_KEYS, } from "./item-metadata-contract.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
  *
@@ -93,85 +94,6 @@ export const TYPE_TO_FOLDER = {
     Meeting: "meetings",
     Plan: "plans",
 };
-/** Portable project-context fields shared by storage order and structured mutation IO. */
-export const ITEM_PROJECT_CONTEXT_KEYS = [
-    "goal",
-    "objective",
-    "value",
-    "impact",
-    "outcome",
-    "why_now",
-    "parent",
-    "reviewer",
-    "risk",
-    "confidence",
-    "sprint",
-    "release",
-    "blocked_by",
-    "blocked_reason",
-    "unblock_note",
-    "reporter",
-    "severity",
-    "environment",
-    "repro_steps",
-    "resolution",
-    "expected_result",
-    "actual_result",
-];
-/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
-export const ITEM_METADATA_KEY_ORDER = [
-    "id",
-    "title",
-    "description",
-    "type",
-    "pm_format_version",
-    "source_type",
-    "type_options",
-    "status",
-    "priority",
-    "tags",
-    "created_at",
-    "updated_at",
-    "deadline",
-    "reminders",
-    "events",
-    "closed_at",
-    "completed_at",
-    "assignee",
-    "claim_principal",
-    "source_owner",
-    "author",
-    "estimated_minutes",
-    "acceptance_criteria",
-    "design",
-    "external_ref",
-    "definition_of_ready",
-    "order",
-    ...ITEM_PROJECT_CONTEXT_KEYS,
-    "affected_version",
-    "fixed_version",
-    "component",
-    "regression",
-    "customer_impact",
-    "dependencies",
-    "comments",
-    "notes",
-    "learnings",
-    "files",
-    "tests",
-    "test_runs",
-    "docs",
-    "close_reason",
-    "duplicate_of",
-    "plan_mode",
-    "plan_scope",
-    "plan_harness",
-    "plan_resume_context",
-    "plan_validation",
-    "plan_decisions",
-    "plan_discoveries",
-    "plan_steps",
-];
 /** Public contract for governance preset defaults, shared by SDK and presentation-layer consumers. */
 export const GOVERNANCE_PRESET_DEFAULTS = {
     minimal: {
@@ -480,4 +402,4 @@ export function resolveTelemetryErrorCategory(errorCode) {
     return "unknown";
 }
 //# sourceMappingURL=constants.js.map
-//# debugId=45e1dcb9-d2d6-52d7-b0b0-a57556a3fb03
+//# debugId=70cce114-b8a7-5770-ae42-eec473515709

package/dist/core/shared/item-metadata-contract.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module core/shared/item-metadata-contract
+ *
+ * Declares the dependency-free canonical item metadata vocabulary shared by
+ * storage, query projections, generated contracts, and package consumers.
+ */
+/** Portable project-context fields shared by storage order and structured mutation IO. */
+export declare const ITEM_PROJECT_CONTEXT_KEYS: readonly ["goal", "objective", "value", "impact", "outcome", "why_now", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "unblock_note", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result"];
+declare const ITEM_METADATA_KEY_ORDER_VALUES: readonly ["id", "title", "description", "type", "pm_format_version", "source_type", "type_options", "status", "priority", "tags", "created_at", "updated_at", "deadline", "reminders", "events", "closed_at", "completed_at", "assignee", "claim_principal", "source_owner", "author", "estimated_minutes", "acceptance_criteria", "design", "external_ref", "definition_of_ready", "order", "goal", "objective", "value", "impact", "outcome", "why_now", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "unblock_note", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result", "affected_version", "fixed_version", "component", "regression", "customer_impact", "dependencies", "comments", "notes", "learnings", "files", "tests", "test_runs", "docs", "close_reason", "duplicate_of", "plan_mode", "plan_scope", "plan_harness", "plan_resume_context", "plan_validation", "plan_decisions", "plan_discoveries", "plan_steps"];
+/** Literal union of every canonical built-in item metadata key. */
+export type ItemMetadataKey = (typeof ITEM_METADATA_KEY_ORDER_VALUES)[number];
+/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
+export declare const ITEM_METADATA_KEY_ORDER: ReadonlyArray<string>;
+export {};

package/dist/core/shared/item-metadata-contract.js

@@ -0,0 +1,90 @@
+/**
+ * @module core/shared/item-metadata-contract
+ *
+ * Declares the dependency-free canonical item metadata vocabulary shared by
+ * storage, query projections, generated contracts, and package consumers.
+ */
+/** Portable project-context fields shared by storage order and structured mutation IO. */
+
+!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]="27c5eac3-4580-5f6f-8ae9-b04d0281766d")}catch(e){}}();
+export const ITEM_PROJECT_CONTEXT_KEYS = [
+    "goal",
+    "objective",
+    "value",
+    "impact",
+    "outcome",
+    "why_now",
+    "parent",
+    "reviewer",
+    "risk",
+    "confidence",
+    "sprint",
+    "release",
+    "blocked_by",
+    "blocked_reason",
+    "unblock_note",
+    "reporter",
+    "severity",
+    "environment",
+    "repro_steps",
+    "resolution",
+    "expected_result",
+    "actual_result",
+];
+const ITEM_METADATA_KEY_ORDER_VALUES = [
+    "id",
+    "title",
+    "description",
+    "type",
+    "pm_format_version",
+    "source_type",
+    "type_options",
+    "status",
+    "priority",
+    "tags",
+    "created_at",
+    "updated_at",
+    "deadline",
+    "reminders",
+    "events",
+    "closed_at",
+    "completed_at",
+    "assignee",
+    "claim_principal",
+    "source_owner",
+    "author",
+    "estimated_minutes",
+    "acceptance_criteria",
+    "design",
+    "external_ref",
+    "definition_of_ready",
+    "order",
+    ...ITEM_PROJECT_CONTEXT_KEYS,
+    "affected_version",
+    "fixed_version",
+    "component",
+    "regression",
+    "customer_impact",
+    "dependencies",
+    "comments",
+    "notes",
+    "learnings",
+    "files",
+    "tests",
+    "test_runs",
+    "docs",
+    "close_reason",
+    "duplicate_of",
+    "plan_mode",
+    "plan_scope",
+    "plan_harness",
+    "plan_resume_context",
+    "plan_validation",
+    "plan_decisions",
+    "plan_discoveries",
+    "plan_steps",
+];
+/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */
+export const ITEM_METADATA_KEY_ORDER = ITEM_METADATA_KEY_ORDER_VALUES;
+//# sourceMappingURL=item-metadata-contract.js.map
+//# debugId=27c5eac3-4580-5f6f-8ae9-b04d0281766d

package/dist/core/store/item-store.d.ts

@@ -50,6 +50,66 @@ declare function buildDidYouMeanSuggestions(pmRoot: string, badId: string, idPre
 /** Implements build item not found error for the public runtime surface of this module. */
 export declare function buildItemNotFoundError(pmRoot: string, badId: string, idPrefix: string, typeToFolder: Record<string, string>): Promise<PmCliError>;
 declare function bypassesAssigneeConflict(op: string, bypassAssigneeConflict?: boolean): boolean;
+interface ItemMutationResult {
+    item: ItemMetadata;
+    body: string;
+    changedFields: string[];
+    warnings: string[];
+}
+interface ItemMutationParams {
+    pmRoot: string;
+    settings: PmSettings;
+    id: string;
+    op: string;
+    author: string;
+    message?: string;
+    /** Structured immutable context attached to the appended history entry. */
+    historyContext?: Record<string, unknown>;
+    force?: boolean;
+    bypassAssigneeConflict?: boolean;
+    skipNoop?: boolean;
+    extensionFieldNames?: readonly string[];
+    typeToFolder?: Record<string, string>;
+    mutate: (document: ItemDocument) => {
+        changedFields: string[];
+        warnings?: string[];
+    } | Promise<{
+        changedFields: string[];
+        warnings?: string[];
+    }>;
+}
+/** Mutate one item while attaching structured context to its immutable history event. */
+export declare function mutateItemWithHistoryContext(params: {
+    pmRoot: string;
+    settings: PmSettings;
+    id: string;
+    op: string;
+    author: string;
+    message?: string;
+    /** Structured immutable context attached to the appended history entry. */
+    historyContext?: Record<string, unknown>;
+    force?: boolean;
+    bypassAssigneeConflict?: boolean;
+    skipNoop?: boolean;
+    extensionFieldNames?: readonly string[];
+    typeToFolder?: Record<string, string>;
+    mutate: (document: ItemDocument) => {
+        changedFields: string[];
+        warnings?: string[];
+    } | Promise<{
+        changedFields: string[];
+        warnings?: string[];
+    }>;
+}): Promise<{
+    item: ItemMetadata;
+    body: string;
+    changedFields: string[];
+    warnings: string[];
+}>;
+/** Mutate one item while resolving structured history context after its locked mutation. */
+export declare function mutateItemWithHistoryContextResolver(params: Omit<ItemMutationParams, "historyContext"> & {
+    resolveHistoryContext: () => Record<string, unknown> | undefined;
+}): Promise<ItemMutationResult>;
 /** Implements mutate item for the public runtime surface of this module. */
 export declare function mutateItem(params: {
     pmRoot: string;

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="d24d61bf-7db8-5f35-8dbc-5ef93ec8220b")}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]="b6db139b-7646-58f9-96af-d3c65bf7ddf6")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -20,7 +20,7 @@ import { acquireLock } from "../lock/lock.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
 import { normalizeItemId, normalizeRawItemId } from "../item/id.js";
 import { acquireItemMetadataDerivedIndexLock, listAllDocumentCandidatesCached, listAllDocumentsCached, listAllDocumentsCachedLight, refreshItemMetadataDerivedIndex, } from "./item-metadata-cache.js";
-import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS, } from "./paths.js";
+import { getHistoryPath, getItemPath, ITEM_FILE_EXTENSIONS } from "./paths.js";
 import { resolveGovernanceKnobs } from "./settings.js";
 import { resolveClaimPrincipal } from "../shared/author.js";
 import { nowIso } from "../shared/time.js";
@@ -377,8 +377,7 @@ async function rollbackMutatedItemWrite(params) {
     }
     await writeFileAtomic(params.originalItemPath, params.originalRaw);
 }
-/** Implements mutate item for the public runtime surface of this module. */
-export async function mutateItem(params) {
+async function mutateItemWithDeferredHistoryContext(params) {
     const prepared = await prepareLockedItem({
         pmRoot: params.pmRoot,
         settings: params.settings,
@@ -409,6 +408,7 @@ export async function mutateItem(params) {
                 warnings: [...parseWarnings, ...(mutation.warnings ?? [])],
             };
         }
+        const historyContext = params.resolveHistoryContext?.();
         mutableDocument.metadata.updated_at = nowIso();
         const afterDocument = canonicalDocument(mutableDocument, {
             schema: params.settings.schema,
@@ -469,6 +469,7 @@ export async function mutateItem(params) {
                 before: beforeDocument,
                 after: afterDocument,
                 message: params.message,
+                context: historyContext,
             });
             try {
                 await appendHistoryEntry(historyPath, entry);
@@ -547,6 +548,22 @@ export async function mutateItem(params) {
         await releaseLock();
     }
 }
+/** Mutate one item while attaching structured context to its immutable history event. */
+export async function mutateItemWithHistoryContext(params) {
+    const { historyContext, ...mutationParams } = params;
+    return mutateItemWithDeferredHistoryContext({
+        ...mutationParams,
+        resolveHistoryContext: () => historyContext,
+    });
+}
+/** Mutate one item while resolving structured history context after its locked mutation. */
+export async function mutateItemWithHistoryContextResolver(params) {
+    return mutateItemWithDeferredHistoryContext(params);
+}
+/** Mutate one item through the compatibility overload while preserving transactional storage and immutable history semantics. */
+export async function mutateItem(params) {
+    return mutateItemWithDeferredHistoryContext(params);
+}
 /** Public contract for item store test only, shared by SDK and presentation-layer consumers. */
 export const itemStoreTestOnly = {
     appendWarning,
@@ -710,4 +727,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=d24d61bf-7db8-5f35-8dbc-5ef93ec8220b
+//# debugId=b6db139b-7646-58f9-96af-d3c65bf7ddf6

package/dist/sdk/agent/closed-domain-contracts.d.ts

@@ -0,0 +1,25 @@
+/** A closed-domain refusal that can be executed and recovered automatically. */
+export interface PmClosedDomainContract {
+    /** Stable assurance identity. */
+    probe_id: string;
+    /** Public command accepting the constrained flag. */
+    command: string;
+    /** Constrained option spelling. */
+    flag: string;
+    /** Invalid token used to prove the refusal path. */
+    rejected_value: string;
+    /** Exact argv that must refuse the invalid token. */
+    refusal_args: readonly string[];
+    /** Complete stable core domain accepted by the command. */
+    allowed_values: readonly string[];
+    /** Exact argv expected in the refusal's executable recovery. */
+    suggested_retry_args: readonly string[];
+    /** Stable machine-readable error code that owns the refusal. */
+    error_code: "projection_options_mutually_exclusive" | "unknown_context_intent" | "unknown_field_projection";
+    /** Whether a complete accepted-value domain is required in the refusal. */
+    allowed_values_required?: boolean;
+}
+/** Return the complete stable core refusal corpus shared by every public surface. */
+export declare function listCoreClosedDomainContracts(): PmClosedDomainContract[];
+/** Render a compact but complete core-domain description for command help. */
+export declare function renderPmClosedDomainHelp(command: string, flag: "--fields" | "--for"): string;

package/dist/sdk/agent/closed-domain-contracts.js

@@ -0,0 +1,140 @@
+/**
+ * @module sdk/agent/closed-domain-contracts
+ *
+ * Declares executable closed-domain refusals once for SDK consumers, CLI help,
+ * and repository assurance. Runtime schema fields can extend field domains
+ * without changing the stable core corpus.
+ */
+
+!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]="35d4f3d7-7ec2-5a8b-bd96-f7e73c658737")}catch(e){}}();
+import { PM_CONTEXT_INTENT_CONTRACTS } from "../context-intent-contracts.js";
+import { LIST_COMMAND_DEFAULT_PROJECTIONS, listGetProjectionFields, listListProjectionFields, listSearchProjectionFields, } from "../query/projection-contracts.js";
+const REJECTED_INTENT = "not-a-declared-intent";
+const REJECTED_FIELD = "not-a-declared-field";
+/** Return the complete stable core refusal corpus shared by every public surface. */
+export function listCoreClosedDomainContracts() {
+    const positionalArguments = {
+        get: ["pm-domain"],
+        search: ["Domain query"],
+    };
+    const intentContracts = [
+        ...new Set(PM_CONTEXT_INTENT_CONTRACTS.map(({ command }) => command)),
+    ].map((command) => {
+        const commandContracts = PM_CONTEXT_INTENT_CONTRACTS.filter((candidate) => candidate.command === command);
+        const contract = commandContracts[0];
+        const positionals = positionalArguments[contract.command] ?? [];
+        return {
+            probe_id: `${contract.command}-invalid-intent`,
+            command: contract.command,
+            flag: "--for",
+            rejected_value: REJECTED_INTENT,
+            refusal_args: [
+                contract.command,
+                ...positionals,
+                "--for",
+                REJECTED_INTENT,
+            ],
+            allowed_values: commandContracts.map(({ intent }) => intent).sort(),
+            suggested_retry_args: [
+                contract.command,
+                ...positionals,
+                "--for",
+                contract.intent,
+            ],
+            error_code: "unknown_context_intent",
+        };
+    });
+    const listFields = listListProjectionFields();
+    const listFieldContracts = Object.keys(LIST_COMMAND_DEFAULT_PROJECTIONS).map((command) => ({
+        probe_id: `${command}-invalid-field`,
+        command,
+        flag: "--fields",
+        rejected_value: REJECTED_FIELD,
+        refusal_args: [command, "--fields", REJECTED_FIELD],
+        allowed_values: listFields,
+        suggested_retry_args: [
+            command,
+            "--fields",
+            "id,title,status",
+            "--limit",
+            "10",
+        ],
+        error_code: "unknown_field_projection",
+    }));
+    const contracts = [
+        ...intentContracts,
+        ...listFieldContracts,
+        {
+            probe_id: "get-invalid-field",
+            command: "get",
+            flag: "--fields",
+            rejected_value: REJECTED_FIELD,
+            refusal_args: ["get", "pm-domain", "--fields", REJECTED_FIELD],
+            allowed_values: listGetProjectionFields(),
+            suggested_retry_args: ["get", "pm-domain", "--fields", "id,title,status"],
+            error_code: "unknown_field_projection",
+        },
+        {
+            probe_id: "list-mutually-exclusive-projection",
+            command: "list",
+            flag: "--projection",
+            rejected_value: "--brief+--full",
+            refusal_args: ["list", "--brief", "--full"],
+            allowed_values: [],
+            suggested_retry_args: ["list", "--brief"],
+            error_code: "projection_options_mutually_exclusive",
+            allowed_values_required: false,
+        },
+        {
+            probe_id: "get-mutually-exclusive-projection",
+            command: "get",
+            flag: "--projection",
+            rejected_value: "--full+--fields",
+            refusal_args: ["get", "pm-domain", "--full", "--fields", "id"],
+            allowed_values: [],
+            suggested_retry_args: ["get", "pm-domain", "--full"],
+            error_code: "projection_options_mutually_exclusive",
+            allowed_values_required: false,
+        },
+        {
+            probe_id: "search-mutually-exclusive-projection",
+            command: "search",
+            flag: "--projection",
+            rejected_value: "--full+--fields",
+            refusal_args: ["search", "Domain query", "--full", "--fields", "id"],
+            allowed_values: [],
+            suggested_retry_args: ["search", "Domain query", "--full"],
+            error_code: "projection_options_mutually_exclusive",
+            allowed_values_required: false,
+        },
+        {
+            probe_id: "search-invalid-field",
+            command: "search",
+            flag: "--fields",
+            rejected_value: REJECTED_FIELD,
+            refusal_args: ["search", "Domain query", "--fields", REJECTED_FIELD],
+            allowed_values: listSearchProjectionFields(),
+            suggested_retry_args: [
+                "search",
+                "Domain query",
+                "--fields",
+                "id,title,status,score",
+            ],
+            error_code: "unknown_field_projection",
+        },
+    ];
+    return contracts.sort((left, right) => left.probe_id.localeCompare(right.probe_id));
+}
+/** Render a compact but complete core-domain description for command help. */
+export function renderPmClosedDomainHelp(command, flag) {
+    const contract = listCoreClosedDomainContracts().find((candidate) => candidate.command === command && candidate.flag === flag);
+    if (!contract)
+        return "No stable core values are declared.";
+    const canonicalValues = contract.allowed_values.filter((value) => !value.startsWith("item."));
+    const runtimeSuffix = flag === "--fields"
+        ? " item.<field> aliases and configured runtime metadata fields are also accepted."
+        : " Configured package and workspace intents may extend this domain.";
+    return `Allowed core values: ${canonicalValues.join("|")}.${runtimeSuffix}`;
+}
+//# sourceMappingURL=closed-domain-contracts.js.map
+//# debugId=35d4f3d7-7ec2-5a8b-bd96-f7e73c658737

package/dist/sdk/agent/refusal-closure.d.ts

@@ -10,15 +10,27 @@ export interface PmRefusalClosureObservation {
     rejected_value: string;
     /** Complete accepted domain emitted by the refusal. */
     allowed_values: readonly string[];
+    /** Stable error code emitted by the refusal. */
+    error_code?: string;
+    /** Contract-owned error code required for this refusal. */
+    expected_error_code?: string;
+    /** Contract-owned complete accepted domain. */
+    expected_allowed_values?: readonly string[];
+    /** Whether an accepted-value domain is required for this refusal class. */
+    allowed_values_required?: boolean;
     /** Exact command emitted for recovery. */
     suggested_retry: string;
+    /** Shell-free argv emitted for safe programmatic recovery. */
+    suggested_retry_args?: readonly string[];
+    /** Contract-owned argv required for deterministic recovery. */
+    expected_suggested_retry_args?: readonly string[];
     /** Whether executing the advertised retry succeeded. */
     retry_succeeded: boolean;
 }
 /** One missing or contradictory recovery primitive. */
 export interface PmRefusalClosureFinding {
     /** Stable finding code. */
-    code: "accepted_rejected_value" | "duplicate_probe" | "empty_corpus" | "missing_allowed_values" | "missing_suggested_retry" | "non_refusal_exit" | "retry_failed";
+    code: "accepted_rejected_value" | "duplicate_probe" | "error_code_mismatch" | "empty_corpus" | "incomplete_allowed_values" | "missing_allowed_values" | "missing_suggested_retry_args" | "missing_suggested_retry" | "non_refusal_exit" | "suggested_retry_args_mismatch" | "retry_failed";
     /** Stable corpus identifier. */
     probe_id: string;
     /** Actionable mismatch detail. */

package/dist/sdk/agent/refusal-closure.js

@@ -5,8 +5,48 @@
  * an agent to recover without another discovery round trip.
  */
 
-!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]="65cfaa41-6f53-5339-8b55-c1a4d3660c5d")}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]="0ec8c375-e58e-5ce4-b0aa-8a8a4dfa0778")}catch(e){}}();
 import { EXIT_CODE } from "../../core/shared/constants.js";
+/** Compare a refusal with its optional SDK-owned exact contract. */
+function listContractObservationFindings(observation) {
+    return [
+        observation.expected_error_code !== undefined &&
+            observation.error_code !== observation.expected_error_code
+            ? {
+                code: "error_code_mismatch",
+                probe_id: observation.probe_id,
+                detail: `Expected error code ${observation.expected_error_code}, received ${observation.error_code ?? "<missing>"}.`,
+            }
+            : undefined,
+        observation.expected_allowed_values !== undefined &&
+            JSON.stringify([...observation.allowed_values].sort()) !==
+                JSON.stringify([...observation.expected_allowed_values].sort())
+            ? {
+                code: "incomplete_allowed_values",
+                probe_id: observation.probe_id,
+                detail: "The refusal's accepted domain differs from the SDK-owned domain contract.",
+            }
+            : undefined,
+        observation.expected_suggested_retry_args !== undefined &&
+            (observation.suggested_retry_args?.length ?? 0) === 0
+            ? {
+                code: "missing_suggested_retry_args",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted shell-free suggested retry arguments.",
+            }
+            : undefined,
+        observation.expected_suggested_retry_args !== undefined &&
+            (observation.suggested_retry_args?.length ?? 0) > 0 &&
+            JSON.stringify(observation.suggested_retry_args) !==
+                JSON.stringify(observation.expected_suggested_retry_args)
+            ? {
+                code: "suggested_retry_args_mismatch",
+                probe_id: observation.probe_id,
+                detail: "The refusal's suggested retry arguments differ from the SDK-owned contract.",
+            }
+            : undefined,
+    ];
+}
 /** Return every closure defect contributed by one unique observation. */
 function listObservationFindings(observation) {
     return [
@@ -17,7 +57,8 @@ function listObservationFindings(observation) {
                 detail: `${observation.entrypoint} returned exit code ${observation.exit_code}; a structured usage refusal must return ${EXIT_CODE.USAGE}.`,
             }
             : undefined,
-        observation.allowed_values.length === 0
+        observation.allowed_values_required !== false &&
+            observation.allowed_values.length === 0
             ? {
                 code: "missing_allowed_values",
                 probe_id: observation.probe_id,
@@ -45,6 +86,7 @@ function listObservationFindings(observation) {
                 detail: "The advertised suggested retry did not succeed.",
             }
             : undefined,
+        ...listContractObservationFindings(observation),
     ];
 }
 /** Score structured closed-domain refusals and executable retries. */
@@ -89,4 +131,4 @@ export function scorePmRefusalClosure(observations) {
     };
 }
 //# sourceMappingURL=refusal-closure.js.map
-//# debugId=65cfaa41-6f53-5339-8b55-c1a4d3660c5d
+//# debugId=0ec8c375-e58e-5ce4-b0aa-8a8a4dfa0778