@unbrained/pm-cli 2026.9.4 → 2026.9.5

package/dist/core/item/actionability.js

@@ -10,9 +10,15 @@
  * `blocked_by` resolution a single source of truth.
  */
 
-!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]="0605f770-d868-5fe9-a186-45f00d2e93b4")}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]="7d98ca40-57e8-5afe-8e9d-b694da0130d1")}catch(e){}}();
 import { isTerminalStatus, normalizeStatusForRegistry } from "./status.js";
+import { BUILTIN_ITEM_EXECUTION_ROLES, resolveTypeDefinition } from "./type-registry.js";
 import { isExternalDependencyReference, isExternalDependencySourceKind, } from "./dependency-reference.js";
+/** Resolve dispatch semantics once for SDK callers, honoring custom and extension type aliases before built-in defaults. */
+export function resolveItemExecutionRole(type, registry) {
+    const definition = registry === undefined ? undefined : resolveTypeDefinition(type, registry);
+    return definition?.execution_role ?? BUILTIN_ITEM_EXECUTION_ROLES[type.trim().toLowerCase()] ?? "agent";
+}
 /** Dependency kind that marks "this item is blocked by the referenced item". */
 const BLOCKED_BY_DEPENDENCY_KIND = "blocked_by";
 /** Reverse dependency kind that marks "this item blocks the referenced item". */
@@ -177,6 +183,24 @@ export function collectDependencyBlockedIds(corpus, statusRegistry) {
     }
     return blocked;
 }
+/** Select dispatch candidates from a classified report while retaining held-out worklists. Ownership and ranking remain caller responsibilities. */
+export function selectActionableEntries(report, statusRegistry, options = {}, typeRegistry) {
+    const candidates = [...report.ready, ...report.decisions, ...report.gates];
+    if (options.includeContainers === true) {
+        candidates.push(...report.containers.filter((entry) => entry.open_blockers.length === 0 && !statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(entry.item.status, statusRegistry))));
+    }
+    const selected = { ready: [], decisions: [], gates: [] };
+    for (const entry of candidates) {
+        const role = resolveItemExecutionRole(entry.item.type, typeRegistry);
+        if (role === "human" && options.includeDecisions !== true)
+            selected.decisions.push(entry);
+        else if (role === "gate" && options.includeGates !== true)
+            selected.gates.push(entry);
+        else
+            selected.ready.push(entry);
+    }
+    return selected;
+}
 /** Resolves the registry's active status set, falling back to just the canonical open status when a custom schema declares none — the same safety net `pm context` applies so the report never misclassifies every item as inactive. */
 function resolveActiveStatusSet(statusRegistry) {
     /* c8 ignore start -- fallback applies only to custom schemas that intentionally define zero active statuses */
@@ -242,7 +266,7 @@ function indexCorpus(corpus) {
  * blockers and the non-terminal items it would unblock. Returned lists preserve
  * the candidate order so the caller can apply its own ranking.
  */
-export function computeActionabilityReport(candidates, corpus, statusRegistry) {
+export function computeActionabilityReport(candidates, corpus, statusRegistry, typeRegistry) {
     const { itemsById, childrenByParent, blockedByReverse, blockerIdsByItem } = indexCorpus(corpus);
     const activeStatuses = new Set([
         ...resolveActiveStatusSet(statusRegistry),
@@ -255,16 +279,14 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
         .map((entry) => normalizeItemId(entry.id)));
     const ready = [];
     const blocked = [];
+    const containers = [];
+    const decisions = [];
+    const gates = [];
     let activeCount = 0;
-    let containerCount = 0;
     for (const item of candidates) {
         if (!activeStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)))
             continue;
         activeCount += 1;
-        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
-            containerCount += 1;
-            continue;
-        }
         const openBlockers = resolveItemBlockersWithIndex(item, itemsById, statusRegistry, blockerIdsByItem).filter((blocker) => !blocker.resolved);
         const unblocks = (blockedByReverse.get(normalizeItemId(item.id)) ?? [])
             .filter((dependentId) => nonTerminalIds.has(normalizeItemId(dependentId)))
@@ -274,9 +296,19 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
             open_blockers: openBlockers,
             unblocks,
         };
+        if (hasOpenDescendant(item.id, childrenByParent, statusRegistry)) {
+            containers.push(entry);
+            continue;
+        }
         const lifecycleBlocked = statusRegistry.blocked_statuses.has(normalizeStatusForRegistry(item.status, statusRegistry));
         if (openBlockers.length === 0 && !lifecycleBlocked) {
-            ready.push(entry);
+            const role = resolveItemExecutionRole(item.type, typeRegistry);
+            if (role === "human")
+                decisions.push(entry);
+            else if (role === "gate")
+                gates.push(entry);
+            else
+                ready.push(entry);
         }
         else {
             blocked.push(entry);
@@ -285,9 +317,12 @@ export function computeActionabilityReport(candidates, corpus, statusRegistry) {
     return {
         ready,
         blocked,
+        containers,
+        decisions,
+        gates,
         active_count: activeCount,
-        container_count: containerCount,
+        container_count: containers.length,
     };
 }
 //# sourceMappingURL=actionability.js.map
-//# debugId=0605f770-d868-5fe9-a186-45f00d2e93b4
+//# debugId=7d98ca40-57e8-5afe-8e9d-b694da0130d1

package/dist/core/item/id.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Id.
  */
 
-!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]="6b3f1585-ab12-57ca-80eb-d3cebc384c52")}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]="04f02467-a4ee-5616-9fbf-3df1141efccf")}catch(e){}}();
 import crypto from "node:crypto";
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
@@ -60,11 +60,13 @@ function randomToken(length) {
     }
     return token;
 }
+/** Reserve an identity when either a live item path or its retained history exists. */
 async function idExists(pmRoot, id, typeToFolder) {
     const checks = [...new Set(Object.values(typeToFolder))].flatMap((folder) => [
         path.join(pmRoot, folder, `${id}.md`),
         path.join(pmRoot, folder, `${id}.toon`),
     ]);
+    checks.push(path.join(pmRoot, "history", `${id}.jsonl`));
     return (await Promise.all(checks.map((target) => pathExists(target)))).some(Boolean);
 }
 /** Bounds accepted for the configurable random id token length (`ids.token_length`). */
@@ -95,8 +97,10 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     while (tokenLength <= maxTokenLength) {
         for (let i = 0; i < 32; i += 1) {
             const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;
-            if (options.probeExisting === false ||
-                !(await idExists(pmRoot, id, options.typeToFolder ?? TYPE_TO_FOLDER))) {
+            const occupied = await (options.probeExisting === false
+                ? pathExists(path.join(pmRoot, "history", `${id}.jsonl`))
+                : idExists(pmRoot, id, options.typeToFolder ?? TYPE_TO_FOLDER));
+            if (!occupied) {
                 return id;
             }
             attempts += 1;
@@ -106,4 +110,4 @@ export async function generateItemId(pmRoot, prefix, options = {}) {
     throw new Error(`Unable to generate unique id after ${attempts} attempts`);
 }
 //# sourceMappingURL=id.js.map
-//# debugId=6b3f1585-ab12-57ca-80eb-d3cebc384c52
+//# debugId=04f02467-a4ee-5616-9fbf-3df1141efccf

package/dist/core/item/item-type-definition.d.ts

@@ -38,6 +38,8 @@ export interface NormalizeItemTypeDefinitionOptions {
     /** How to resolve a raw policy `command` value (defaults to {@link keepPolicyCommand}). */
     resolvePolicyCommand?: ResolvePolicyCommand;
 }
+/** Validate an execution role before a settings or extension definition enters scheduling. Unknown values fail instead of silently enabling dispatch. */
+export declare function parseItemExecutionRole(value: unknown): ItemTypeDefinition["execution_role"];
 /**
  * Normalize a full {@link ItemTypeDefinition}, returning null when the name is blank.
  *

package/dist/core/item/item-type-definition.js

@@ -15,7 +15,7 @@
  */
 /** Dedupe + sort a string list: trim, drop blanks, unique, locale-sorted. */
 
-!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]="815165a9-27a7-5933-adae-c7e55330c8e4")}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]="f02cb2e7-2d5f-5cc8-8a60-18db78b50da0")}catch(e){}}();
 export function normalizeItemTypeStringList(values) {
     return [
         ...new Set((values ?? [])
@@ -85,6 +85,12 @@ function optionalNonEmptyString(value) {
     const normalized = value?.trim();
     return normalized && normalized.length > 0 ? normalized : undefined;
 }
+/** Validate an execution role before a settings or extension definition enters scheduling. Unknown values fail instead of silently enabling dispatch. */
+export function parseItemExecutionRole(value) {
+    if (value === undefined || value === "agent" || value === "human" || value === "gate")
+        return value;
+    throw new Error("Item type execution_role must be agent, human, or gate.");
+}
 /**
  * Normalize a full {@link ItemTypeDefinition}, returning null when the name is blank.
  *
@@ -113,6 +119,7 @@ export function normalizeItemTypeDefinition(definition, options = {}) {
         name,
         description: optionalNonEmptyString(definition.description),
         default_status: optionalNonEmptyString(definition.default_status),
+        ...(definition.execution_role === undefined ? {} : { execution_role: parseItemExecutionRole(definition.execution_role) }),
         folder: optionalNonEmptyString(definition.folder),
         aliases: aliases.length > 0 ? aliases : undefined,
         required_create_fields: normalizeOptionalStringList(definition.required_create_fields, hasRequiredCreateFields),
@@ -124,4 +131,4 @@ export function normalizeItemTypeDefinition(definition, options = {}) {
     };
 }
 //# sourceMappingURL=item-type-definition.js.map
-//# debugId=815165a9-27a7-5933-adae-c7e55330c8e4
+//# debugId=f02cb2e7-2d5f-5cc8-8a60-18db78b50da0

package/dist/core/item/type-registry.d.ts

@@ -1,5 +1,7 @@
 import type { ExtensionRegistrationRegistry } from "../extensions/loader.js";
-import type { ItemTypeCommandOptionPolicy, ItemTypeOptionDefinition, PmSettings } from "../../types/index.js";
+import type { ItemTypeCommandOptionPolicy, ItemTypeDefinition, ItemTypeOptionDefinition, PmSettings } from "../../types/index.js";
+/** Default dispatch roles for built-in types whose work requires human input or outcome verification. Custom definitions can override these through the same registry. */
+export declare const BUILTIN_ITEM_EXECUTION_ROLES: Readonly<Record<string, "human" | "gate">>;
 /** Fallback required create fields used when callers do not provide an override. */
 export declare const DEFAULT_REQUIRED_CREATE_FIELDS: readonly ["title", "description", "status", "priority", "tags", "body", "deadline", "estimatedMinutes", "acceptanceCriteria", "author", "message", "assignee"];
 /** Fallback required create repeatables used when callers do not provide an override. */
@@ -31,6 +33,8 @@ export interface ResolvedItemTypeDefinition {
     aliases: string[];
     /** Optional per-type status applied at create time when `--status` is omitted. */
     default_status?: string;
+    /** Effective dispatch role; absent legacy definitions are resolved through the built-in defaults. */
+    execution_role?: ItemTypeDefinition["execution_role"];
     /** Value that configures or reports required create fields for this contract. */
     required_create_fields: string[];
     /** Value that configures or reports required create repeatables for this contract. */

package/dist/core/item/type-registry.js

@@ -4,11 +4,13 @@
  * Defines item parsing, formatting, and lifecycle helpers for Type Registry.
  */
 
-!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]="88b2ed4e-b5fd-5014-abf1-c163db033abf")}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]="506efdc7-b04e-5023-ab59-57ede87558f9")}catch(e){}}();
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
 import { ITEM_TYPE_VALUES } from "../../types/index.js";
-import { normalizeItemTypeDefinition as normalizeSharedItemTypeDefinition, normalizeItemTypeStringList, strictPolicyCommand, } from "./item-type-definition.js";
+import { normalizeItemTypeDefinition as normalizeSharedItemTypeDefinition, normalizeItemTypeStringList, strictPolicyCommand, parseItemExecutionRole, } from "./item-type-definition.js";
+/** Default dispatch roles for built-in types whose work requires human input or outcome verification. Custom definitions can override these through the same registry. */
+export const BUILTIN_ITEM_EXECUTION_ROLES = Object.freeze({ decision: "human", milestone: "gate" });
 /** Fallback required create fields used when callers do not provide an override. */
 export const DEFAULT_REQUIRED_CREATE_FIELDS = [
     "title",
@@ -421,6 +423,7 @@ function coerceTypeDefinitionFromUnknown(raw) {
         name,
         description,
         default_status: defaultStatus,
+        execution_role: parseItemExecutionRole(record.execution_role),
         folder,
         aliases: readStringArray(record, "aliases"),
         required_create_fields: readStringArray(record, "required_create_fields"),
@@ -462,6 +465,7 @@ function buildResolvedTypeDefinition(normalizedDefinition, existing) {
         toDefaultFolder(keepName));
     const resolvedDefinition = {
         name: keepName,
+        execution_role: normalizedDefinition.execution_role,
         folder,
         aliases: normalizeItemTypeStringList([
             ...(existing?.aliases ?? []),
@@ -488,7 +492,7 @@ function applyTypeDefinitions(source, target) {
         }
         const lowerName = normalizedDefinition.name.toLowerCase();
         const existing = target.get(lowerName);
-        target.set(lowerName, buildResolvedTypeDefinition(normalizedDefinition, existing));
+        target.set(lowerName, buildResolvedTypeDefinition({ ...normalizedDefinition, execution_role: normalizedDefinition.execution_role ?? existing?.execution_role }, existing));
     }
 }
 function collectExtensionTypeDefinitions(registrations) {
@@ -516,6 +520,7 @@ export function resolveItemTypeRegistry(settings, extensionRegistrations = null)
     for (const builtin of ITEM_TYPE_VALUES) {
         byLowerName.set(builtin.toLowerCase(), {
             name: builtin,
+            execution_role: BUILTIN_ITEM_EXECUTION_ROLES[builtin.toLowerCase()] ?? "agent",
             folder: TYPE_TO_FOLDER[builtin],
             aliases: [],
             required_create_fields: [...DEFAULT_REQUIRED_CREATE_FIELDS],
@@ -708,4 +713,4 @@ export function validateTypeOptions(typeName, rawTypeOptions, registry) {
     };
 }
 //# sourceMappingURL=type-registry.js.map
-//# debugId=88b2ed4e-b5fd-5014-abf1-c163db033abf
+//# debugId=506efdc7-b04e-5023-ab59-57ede87558f9

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

@@ -53,6 +53,14 @@ export interface PmCliErrorRecoveryPayload {
 export interface PmCliErrorContext {
     /** Value that configures or reports code for this contract. */
     code?: string;
+    /** Item whose document could not be decoded or parsed. */
+    item_id?: string;
+    /** Exact filesystem path of the unreadable item document. */
+    item_path?: string;
+    /** Original document size before decoding or parsing. */
+    byte_length?: number;
+    /** Whether the original item document contained no bytes. */
+    empty?: boolean;
     /** Stable failure class within the operation-specific error code. */
     reason?: string;
     /** Metadata field responsible for a validation failure, when known. */

package/dist/core/shared/errors.js

@@ -1,6 +1,6 @@
 /** Implements the exported pm cli error runtime abstraction for core/shared/errors.ts. */
 
-!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]="922e2e27-1499-5466-98e4-322d0d742e40")}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]="9ab4b378-900c-5a2a-9237-b1d8d4f2ae13")}catch(e){}}();
 export class PmCliError extends Error {
     /** Value that configures or reports exit code for this contract. */
     exitCode;
@@ -18,4 +18,4 @@ export class PmCliError extends Error {
     }
 }
 //# sourceMappingURL=errors.js.map
-//# debugId=922e2e27-1499-5466-98e4-322d0d742e40
+//# debugId=9ab4b378-900c-5a2a-9237-b1d8d4f2ae13

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

@@ -25,6 +25,20 @@ export declare function readLocatedItem(item: LocatedItem, options?: {
     raw: string;
     document: ItemDocument;
 }>;
+/**
+ * Read once and retain a recoverable parse failure beside its exact text snapshot.
+ * Filesystem and merge-conflict errors still throw; callers must explicitly
+ * reconstruct an invalid document before performing any mutation.
+ */
+export declare function readLocatedItemSnapshot(item: LocatedItem, options?: Parameters<typeof readLocatedItem>[1]): Promise<{
+    raw: string;
+    document: ItemDocument;
+    error: null;
+} | {
+    raw: string;
+    document: null;
+    error: PmCliError;
+}>;
 /** Implements list all item metadata for the public runtime surface of this module. */
 export declare function listAllItemMetadata(pmRoot: string, preferredFormat?: ItemFormat, typeToFolder?: Record<string, string>, warnings?: string[], schema?: RuntimeSchemaSettings): Promise<ItemMetadata[]>;
 /**

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]="bffd3114-3e85-58ae-90c7-eea5069cdb89")}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]="c3390c01-c153-5baa-b9bd-07ea8d34828f")}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";
@@ -18,6 +18,7 @@ import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "..
 import { resolveItemTypeRegistry } from "../item/type-registry.js";
 import { acquireLock } from "../lock/lock.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
+import { isUtf8 } from "node:buffer";
 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";
@@ -96,18 +97,55 @@ export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredForma
 }
 /** Implements read located item for the public runtime surface of this module. */
 export async function readLocatedItem(item, options = {}) {
-    const raw = await fs.readFile(item.itemPath, "utf8");
+    const snapshot = await readLocatedItemSnapshot(item, options);
+    if (snapshot.error !== null)
+        throw snapshot.error;
+    return { raw: snapshot.raw, document: snapshot.document };
+}
+/**
+ * Read once and retain a recoverable parse failure beside its exact text snapshot.
+ * Filesystem and merge-conflict errors still throw; callers must explicitly
+ * reconstruct an invalid document before performing any mutation.
+ */
+export async function readLocatedItemSnapshot(item, options = {}) {
+    const bytes = await fs.readFile(item.itemPath);
+    if (!isUtf8(bytes)) {
+        throw new PmCliError("Item contains invalid UTF-8; preserve a binary backup before recovering it.", EXIT_CODE.CONFLICT, { code: "item_document_encoding_invalid", item_id: item.id, item_path: item.itemPath, byte_length: bytes.length, empty: false });
+    }
+    const raw = bytes.toString("utf8");
     await runActiveOnReadHooks({
         path: item.itemPath,
         scope: "project",
     });
-    const document = parseItemDocument(raw, {
-        format: item.item_format,
-        schema: options.schema,
-        extensionFieldNames: resolveActiveExtensionFieldNames(options.extensionFieldNames),
-        onWarning: (warning) => appendWarning(options.warnings, warning),
-    });
-    return { raw, document };
+    let document;
+    try {
+        document = parseItemDocument(raw, {
+            format: item.item_format,
+            schema: options.schema,
+            extensionFieldNames: resolveActiveExtensionFieldNames(options.extensionFieldNames),
+            onWarning: (warning) => appendWarning(options.warnings, warning),
+        });
+    }
+    catch (error) {
+        if (error instanceof PmCliError && error.code === "item_document_invalid") {
+            return {
+                raw,
+                document: null,
+                error: new PmCliError(`Cannot read ${item.id} at ${item.itemPath}${bytes.length === 0 ? " (zero-length file)" : ""}: ${error.message}`, error.exitCode, {
+                    ...error.context,
+                    item_id: item.id,
+                    item_path: item.itemPath,
+                    byte_length: bytes.length,
+                    empty: bytes.length === 0,
+                    nextSteps: [
+                        `Run pm history ${item.id} --full, then pm restore ${item.id} <version> to recover a recorded state.`,
+                    ],
+                }),
+            };
+        }
+        throw error;
+    }
+    return { raw, document, error: null };
 }
 /** Implements list all item metadata for the public runtime surface of this module. */
 export async function listAllItemMetadata(pmRoot, preferredFormat, typeToFolder = TYPE_TO_FOLDER, warnings, schema) {
@@ -649,4 +687,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=bffd3114-3e85-58ae-90c7-eea5069cdb89
+//# debugId=c3390c01-c153-5baa-b9bd-07ea8d34828f

package/dist/core/store/settings-validator.js

@@ -12,7 +12,7 @@
  * byte-identical to the previous implementation.
  */
 
-!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]="0e135793-d2ed-505b-b73e-6db55218d8af")}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]="c9cac741-16ba-5466-806f-bf8881a2ffa2")}catch(e){}}();
 import { GOVERNANCE_PRESET_VALUES, RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, RUNTIME_STATUS_ROLE_VALUES, RUNTIME_UNKNOWN_FIELD_POLICY_VALUES, } from "../../types.js";
 // Generic over `never` so it is assignable to every `Outcome<T>`.
 const FAIL = { ok: false };
@@ -137,6 +137,7 @@ const itemTypeDefinition = vObject({
     // Per-type create-time default status (config-driven); preserved so inline
     // settings.item_types.definitions behave identically to schema/types.json.
     default_status: vOptional(vString),
+    execution_role: vOptional(vLiteral("agent", "human", "gate")),
     folder: vOptional(vString),
     aliases: vOptional(vArray(vString)),
     required_create_fields: vOptional(vArray(vString)),
@@ -418,4 +419,4 @@ export function validateSettings(raw) {
     return { success: true, data: result.value };
 }
 //# sourceMappingURL=settings-validator.js.map
-//# debugId=0e135793-d2ed-505b-b73e-6db55218d8af
+//# debugId=c9cac741-16ba-5466-806f-bf8881a2ffa2

package/dist/sdk/actionability.d.ts

@@ -7,4 +7,4 @@
  * blocker or ready-work classifications without storage or rendering side
  * effects.
  */
-export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, resolveItemExecutionRole, selectActionableEntries, type ActionabilitySelectionOptions, type ActionabilityReport, type ActionableEntry, type ResolvedBlocker, } from "../core/item/actionability.js";

package/dist/sdk/actionability.js

@@ -8,7 +8,7 @@
  * effects.
  */
 
-!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]="cc271a73-9767-54bb-a142-d4d4569e3c6a")}catch(e){}}();
-export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, } from "../core/item/actionability.js";
+!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]="7d393eb0-d24d-55d2-8e4e-e94805d91784")}catch(e){}}();
+export { ACTIONABILITY_ORDERING_KINDS, collectBlockedByIds, collectBlockedByIdsFromCorpus, collectDependencyBlockedIds, computeActionabilityReport, indexBlockedByIds, resolveItemBlockers, resolveItemExecutionRole, selectActionableEntries, } from "../core/item/actionability.js";
 //# sourceMappingURL=actionability.js.map
-//# debugId=cc271a73-9767-54bb-a142-d4d4569e3c6a
+//# debugId=7d393eb0-d24d-55d2-8e4e-e94805d91784

package/dist/sdk/cli-contracts/command-aliases.js

@@ -10,8 +10,17 @@
  * are intentionally absent from default help and completion discovery.
  */
 
-!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]="3c9694bd-3635-5298-abeb-6899c94317ab")}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]="a7934e70-b1ea-5eac-b500-e4b18a6385a6")}catch(e){}}();
 export const PM_COMMAND_ALIAS_CONTRACTS = [
+    {
+        alias: "tests",
+        canonical: "test",
+        canonical_argv: ["test"],
+        lifecycle: "permanent",
+        hidden: false,
+        registration: "bootstrap",
+        owner: "pm-u4t9gp",
+    },
     ...[
         ["fetch", "get"],
         ["read", "get"],
@@ -96,4 +105,4 @@ export function renderPmCommandAliasMigrationHint(contract) {
     return `Deprecated command \`${contract.alias}\`; use \`pm ${contract.canonical_argv.join(" ")}\`.`;
 }
 //# sourceMappingURL=command-aliases.js.map
-//# debugId=3c9694bd-3635-5298-abeb-6899c94317ab
+//# debugId=a7934e70-b1ea-5eac-b500-e4b18a6385a6

package/dist/sdk/cli-contracts/completeness.js

@@ -7,7 +7,7 @@
  * a hand-picked test list.
  */
 
-!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]="f4e5eed5-94c2-536a-8685-e20b735de480")}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]="199e3ef5-93a0-5d93-8f77-d9d12bbc69d4")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -100,6 +100,7 @@ const ACTION_POSITIONAL_PARAMETERS = {
     },
 };
 const ACTION_FLAG_PARAMETER_OVERRIDES = {
+    append: { "--text": "body" },
     assurance: {
         "--tree": "treeId",
         "--owner": "owner",
@@ -139,7 +140,7 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     docs: { "--note": "addNote" },
     comments: { "--full-history": "full" },
     notes: { "--file": "text", "--full-history": "full" },
-    learnings: { "--full-history": "full" },
+    learnings: { "--file": "text", "--full-history": "full" },
     gc: { "--scope": "gcScope" },
     contracts: { "--action": "contractAction" },
     schema: {
@@ -390,4 +391,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=f4e5eed5-94c2-536a-8685-e20b735de480
+//# debugId=199e3ef5-93a0-5d93-8f77-d9d12bbc69d4