@unbrained/pm-cli 2026.3.12 → 2026.5.1

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

@@ -1,8 +1,14 @@
-import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, STATUS_VALUES } from "../../types/index.js";
+import { decode as decodeToon, encode as encodeToon } from "@toon-format/toon";
+import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, } from "../../types/index.js";
+import { coerceRuntimeFieldValue } from "../schema/runtime-field-values.js";
+import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../schema/runtime-schema.js";
+import { normalizeStatusInput } from "./status.js";
 import { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
+import { findFirstMergeConflictMarker } from "../shared/conflict-markers.js";
 import { PmCliError } from "../shared/errors.js";
 import { orderObject } from "../shared/serialization.js";
 import { compareTimestampStrings, isTimestampLiteral } from "../shared/time.js";
+const LINKED_TEST_PM_CONTEXT_MODE_VALUES = new Set(["schema", "tracker", "auto"]);
 function normalizePathValue(value) {
     return value.replaceAll("\\", "/");
 }
@@ -13,6 +19,30 @@ const REQUIRED_STRING_FIELDS = [
     "created_at",
     "updated_at",
 ];
+const STATIC_FRONT_MATTER_FIELD_SET = new Set(FRONT_MATTER_KEY_ORDER);
+function resolveRuntimeSchemaValidationContext(options) {
+    if (!options?.schema) {
+        return undefined;
+    }
+    return {
+        statusRegistry: resolveRuntimeStatusRegistry(options.schema),
+        fieldRegistry: resolveRuntimeFieldRegistry(options.schema),
+        unknownFieldPolicy: options.schema.unknown_field_policy ?? "allow",
+        onWarning: options.onWarning,
+    };
+}
+function runtimeFieldRequiredForType(definition, typeName) {
+    if (!definition.required) {
+        return false;
+    }
+    if (definition.required_types.length === 0) {
+        return true;
+    }
+    return definition.required_types.map((value) => value.toLowerCase()).includes(typeName.trim().toLowerCase());
+}
+function weekdayOrderIndex(value) {
+    return RECURRENCE_WEEKDAY_VALUES.indexOf(value);
+}
 function validationError(message) {
     throw new PmCliError(`Invalid item front matter: ${message}`, EXIT_CODE.GENERIC_FAILURE);
 }
@@ -27,16 +57,62 @@ function assertTimestampField(record, fieldName) {
     const timestamp = rawValue;
     assertFrontMatterCondition(isTimestampLiteral(timestamp), `${fieldName} must be a valid ISO timestamp`);
 }
-function assertValidFrontMatter(frontMatter) {
+function assertValidRecurrenceRule(recurrence) {
+    assertFrontMatterCondition(typeof recurrence === "object" && recurrence !== null && !Array.isArray(recurrence), "event.recurrence must be an object");
+    const recurrenceRecord = recurrence;
+    assertFrontMatterCondition(typeof recurrenceRecord.freq === "string", "event.recurrence.freq must be a string");
+    const frequency = recurrenceRecord.freq.trim().toLowerCase();
+    assertFrontMatterCondition(RECURRENCE_FREQUENCY_VALUES.includes(frequency), `event.recurrence.freq must be one of: ${RECURRENCE_FREQUENCY_VALUES.join(", ")}`);
+    if (recurrenceRecord.interval !== undefined) {
+        assertFrontMatterCondition(typeof recurrenceRecord.interval === "number" &&
+            Number.isInteger(recurrenceRecord.interval) &&
+            recurrenceRecord.interval >= 1, "event.recurrence.interval must be an integer >= 1");
+    }
+    if (recurrenceRecord.count !== undefined) {
+        assertFrontMatterCondition(typeof recurrenceRecord.count === "number" && Number.isInteger(recurrenceRecord.count) && recurrenceRecord.count >= 1, "event.recurrence.count must be an integer >= 1");
+    }
+    if (recurrenceRecord.until !== undefined) {
+        assertFrontMatterCondition(typeof recurrenceRecord.until === "string", "event.recurrence.until must be a string");
+        assertFrontMatterCondition(isTimestampLiteral(recurrenceRecord.until), "event.recurrence.until must be a valid ISO timestamp");
+    }
+    if (recurrenceRecord.by_weekday !== undefined) {
+        assertFrontMatterCondition(Array.isArray(recurrenceRecord.by_weekday), "event.recurrence.by_weekday must be an array");
+        for (const weekday of recurrenceRecord.by_weekday) {
+            assertFrontMatterCondition(typeof weekday === "string", "event.recurrence.by_weekday entries must be strings");
+            const normalizedWeekday = weekday.trim().toLowerCase();
+            assertFrontMatterCondition(RECURRENCE_WEEKDAY_VALUES.includes(normalizedWeekday), `event.recurrence.by_weekday entries must be one of: ${RECURRENCE_WEEKDAY_VALUES.join(", ")}`);
+        }
+    }
+    if (recurrenceRecord.by_month_day !== undefined) {
+        assertFrontMatterCondition(Array.isArray(recurrenceRecord.by_month_day), "event.recurrence.by_month_day must be an array");
+        for (const day of recurrenceRecord.by_month_day) {
+            assertFrontMatterCondition(typeof day === "number" && Number.isInteger(day) && day >= 1 && day <= 31, "event.recurrence.by_month_day entries must be integers 1..31");
+        }
+    }
+    if (recurrenceRecord.exdates !== undefined) {
+        assertFrontMatterCondition(Array.isArray(recurrenceRecord.exdates), "event.recurrence.exdates must be an array");
+        for (const exdate of recurrenceRecord.exdates) {
+            assertFrontMatterCondition(typeof exdate === "string", "event.recurrence.exdates entries must be strings");
+            assertFrontMatterCondition(isTimestampLiteral(exdate), "event.recurrence.exdates entries must be valid ISO timestamps");
+        }
+    }
+}
+function assertValidFrontMatter(frontMatter, runtimeContext) {
     assertFrontMatterCondition(typeof frontMatter === "object" && frontMatter !== null && !Array.isArray(frontMatter), "front matter must be an object");
     const record = frontMatter;
     for (const fieldName of REQUIRED_STRING_FIELDS) {
         assertFrontMatterCondition(typeof record[fieldName] === "string", `${fieldName} is required and must be a string`);
     }
     const itemType = record.type;
-    assertFrontMatterCondition(typeof itemType === "string" && ITEM_TYPE_VALUES.includes(itemType), `type must be one of: ${ITEM_TYPE_VALUES.join(", ")}`);
+    assertFrontMatterCondition(typeof itemType === "string" && itemType.trim().length > 0, "type must be a non-empty string");
     const status = record.status;
-    assertFrontMatterCondition(typeof status === "string" && STATUS_VALUES.includes(status), `status must be one of: ${STATUS_VALUES.join(", ")}`);
+    assertFrontMatterCondition(typeof status === "string" && status.trim().length > 0, "status must be a non-empty string");
+    const statusRegistry = runtimeContext?.statusRegistry;
+    const normalizedStatus = normalizeStatusInput(status, statusRegistry);
+    const statusDomain = statusRegistry
+        ? statusRegistry.definitions.map((definition) => definition.id)
+        : [...STATUS_VALUES];
+    assertFrontMatterCondition(normalizedStatus !== undefined, `status must be one of: ${statusDomain.join(", ")}`);
     const priority = record.priority;
     assertFrontMatterCondition(typeof priority === "number" && Number.isInteger(priority) && [0, 1, 2, 3, 4].includes(priority), "priority must be an integer 0..4");
     const tags = record.tags;
@@ -78,6 +154,48 @@ function assertValidFrontMatter(frontMatter) {
     if (record.deadline !== undefined) {
         assertTimestampField(record, "deadline");
     }
+    if (record.reminders !== undefined) {
+        const reminders = record.reminders;
+        assertFrontMatterCondition(Array.isArray(reminders), "reminders must be an array");
+        for (const reminder of reminders) {
+            assertFrontMatterCondition(typeof reminder === "object" && reminder !== null && !Array.isArray(reminder), "reminders entries must be objects");
+            const reminderRecord = reminder;
+            assertFrontMatterCondition(typeof reminderRecord.at === "string", "reminder.at must be a string");
+            assertFrontMatterCondition(isTimestampLiteral(reminderRecord.at), "reminder.at must be a valid ISO timestamp");
+            assertFrontMatterCondition(typeof reminderRecord.text === "string", "reminder.text must be a string");
+            assertFrontMatterCondition(reminderRecord.text.trim().length > 0, "reminder.text must not be empty");
+        }
+    }
+    if (record.events !== undefined) {
+        const events = record.events;
+        assertFrontMatterCondition(Array.isArray(events), "events must be an array");
+        for (const event of events) {
+            assertFrontMatterCondition(typeof event === "object" && event !== null && !Array.isArray(event), "events entries must be objects");
+            const eventRecord = event;
+            assertFrontMatterCondition(typeof eventRecord.start_at === "string", "event.start_at must be a string");
+            assertFrontMatterCondition(isTimestampLiteral(eventRecord.start_at), "event.start_at must be a valid ISO timestamp");
+            if (eventRecord.end_at !== undefined) {
+                assertFrontMatterCondition(typeof eventRecord.end_at === "string", "event.end_at must be a string");
+                assertFrontMatterCondition(isTimestampLiteral(eventRecord.end_at), "event.end_at must be a valid ISO timestamp");
+                assertFrontMatterCondition(compareTimestampStrings(eventRecord.end_at, eventRecord.start_at) > 0, "event.end_at must be after event.start_at");
+            }
+            for (const stringField of ["title", "description", "location", "timezone"]) {
+                if (eventRecord[stringField] !== undefined) {
+                    assertFrontMatterCondition(typeof eventRecord[stringField] === "string", `event.${stringField} must be a string`);
+                    assertFrontMatterCondition(eventRecord[stringField].trim().length > 0, `event.${stringField} must not be empty`);
+                }
+            }
+            if (eventRecord.all_day !== undefined) {
+                assertFrontMatterCondition(typeof eventRecord.all_day === "boolean", "event.all_day must be a boolean");
+            }
+            if (eventRecord.recurrence !== undefined) {
+                assertValidRecurrenceRule(eventRecord.recurrence);
+                if (eventRecord.recurrence.until !== undefined) {
+                    assertFrontMatterCondition(compareTimestampStrings(eventRecord.recurrence.until, eventRecord.start_at) >= 0, "event.recurrence.until must be at or after event.start_at");
+                }
+            }
+        }
+    }
     if (record.closed_at !== undefined) {
         const closedAt = record.closed_at;
         assertFrontMatterCondition(typeof closedAt === "string", "closed_at must be a string");
@@ -89,6 +207,48 @@ function assertValidFrontMatter(frontMatter) {
             assertFrontMatterCondition(typeof value === "string", `${fieldName} must be a string`);
         }
     }
+    const typeOptions = record.type_options;
+    if (typeOptions !== undefined) {
+        assertFrontMatterCondition(typeof typeOptions === "object" && typeOptions !== null && !Array.isArray(typeOptions), "type_options must be an object");
+        for (const [optionKey, optionValue] of Object.entries(typeOptions)) {
+            assertFrontMatterCondition(optionKey.trim().length > 0, "type_options keys must be non-empty");
+            assertFrontMatterCondition(typeof optionValue === "string", "type_options values must be strings");
+            const optionText = optionValue;
+            assertFrontMatterCondition(optionText.trim().length > 0, "type_options values must be non-empty strings");
+        }
+    }
+    if (runtimeContext?.fieldRegistry) {
+        for (const definition of runtimeContext.fieldRegistry.definitions) {
+            const fieldValue = record[definition.front_matter_key];
+            if (fieldValue === undefined) {
+                if (runtimeFieldRequiredForType(definition, itemType)) {
+                    validationError(`missing required schema field: ${definition.front_matter_key}`);
+                }
+                continue;
+            }
+            try {
+                record[definition.front_matter_key] = coerceRuntimeFieldValue(definition, fieldValue, `metadata field "${definition.front_matter_key}"`);
+            }
+            catch (error) {
+                validationError(error instanceof Error ? error.message.replace(/^Invalid\s+/u, "") : `invalid ${definition.front_matter_key} value`);
+            }
+        }
+    }
+    if (runtimeContext && runtimeContext.unknownFieldPolicy !== "allow") {
+        const knownKeys = new Set(STATIC_FRONT_MATTER_FIELD_SET);
+        for (const definition of runtimeContext.fieldRegistry?.definitions ?? []) {
+            knownKeys.add(definition.front_matter_key);
+        }
+        const unknownKeys = Object.keys(record).filter((key) => !knownKeys.has(key)).sort((left, right) => left.localeCompare(right));
+        if (unknownKeys.length > 0) {
+            if (runtimeContext.unknownFieldPolicy === "reject") {
+                validationError(`unknown schema fields are not allowed: ${unknownKeys.join(", ")}`);
+            }
+            else {
+                runtimeContext.onWarning?.(`item_unknown_schema_fields:${unknownKeys.join(",")}`);
+            }
+        }
+    }
 }
 function sortDependencies(values) {
     if (!values || values.length === 0)
@@ -127,24 +287,166 @@ function sortLogValues(values) {
         return a.author.localeCompare(b.author);
     });
 }
-function sortFiles(values) {
+function sortReminders(values) {
     if (!values || values.length === 0)
         return undefined;
-    return [...values]
+    const normalized = [...values]
+        .map((value) => ({
+        at: value.at,
+        text: value.text.trim(),
+    }))
+        .filter((value) => value.text.length > 0)
+        .sort((a, b) => {
+        const byAt = compareTimestampStrings(a.at, b.at);
+        if (byAt !== 0)
+            return byAt;
+        return a.text.localeCompare(b.text);
+    });
+    return normalized.length === 0 ? undefined : normalized;
+}
+function normalizeRecurrenceRule(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalizedFrequency = value.freq.trim().toLowerCase();
+    if (!RECURRENCE_FREQUENCY_VALUES.includes(normalizedFrequency)) {
+        return undefined;
+    }
+    const byWeekday = Array.from(new Set((value.by_weekday ?? [])
+        .map((weekday) => weekday.trim().toLowerCase())
+        .filter((weekday) => RECURRENCE_WEEKDAY_VALUES.includes(weekday)))).sort((a, b) => weekdayOrderIndex(a) -
+        weekdayOrderIndex(b));
+    const byMonthDay = Array.from(new Set((value.by_month_day ?? [])
+        .filter((day) => Number.isInteger(day) && day >= 1 && day <= 31)
+        .map((day) => day))).sort((a, b) => a - b);
+    const exdates = Array.from(new Set((value.exdates ?? [])
+        .map((timestamp) => timestamp.trim())
+        .filter((timestamp) => isTimestampLiteral(timestamp)))).sort((a, b) => compareTimestampStrings(a, b));
+    const normalized = {
+        freq: normalizedFrequency,
+        interval: value.interval !== undefined && value.interval > 1 ? value.interval : undefined,
+        count: value.count,
+        until: value.until?.trim() || undefined,
+        by_weekday: byWeekday.length > 0 ? byWeekday : undefined,
+        by_month_day: byMonthDay.length > 0 ? byMonthDay : undefined,
+        exdates: exdates.length > 0 ? exdates : undefined,
+    };
+    for (const [key, fieldValue] of Object.entries(normalized)) {
+        if (fieldValue === undefined) {
+            delete normalized[key];
+        }
+    }
+    return normalized;
+}
+function sortEvents(values) {
+    if (!values || values.length === 0) {
+        return undefined;
+    }
+    const normalized = [...values]
+        .map((value) => {
+        const event = {
+            start_at: value.start_at,
+            end_at: value.end_at || undefined,
+            title: value.title?.trim() || undefined,
+            description: value.description?.trim() || undefined,
+            location: value.location?.trim() || undefined,
+            all_day: value.all_day,
+            timezone: value.timezone?.trim() || undefined,
+            recurrence: normalizeRecurrenceRule(value.recurrence),
+        };
+        for (const [key, fieldValue] of Object.entries(event)) {
+            if (fieldValue === undefined) {
+                delete event[key];
+            }
+        }
+        return event;
+    })
+        .sort((a, b) => {
+        const byStart = compareTimestampStrings(a.start_at, b.start_at);
+        if (byStart !== 0)
+            return byStart;
+        const byEnd = (a.end_at ?? "").localeCompare(b.end_at ?? "");
+        if (byEnd !== 0)
+            return byEnd;
+        const byTitle = (a.title ?? "").localeCompare(b.title ?? "");
+        if (byTitle !== 0)
+            return byTitle;
+        const byAllDay = Number(Boolean(a.all_day)) - Number(Boolean(b.all_day));
+        if (byAllDay !== 0)
+            return byAllDay;
+        const byTimezone = (a.timezone ?? "").localeCompare(b.timezone ?? "");
+        if (byTimezone !== 0)
+            return byTimezone;
+        const byLocation = (a.location ?? "").localeCompare(b.location ?? "");
+        if (byLocation !== 0)
+            return byLocation;
+        const byDescription = (a.description ?? "").localeCompare(b.description ?? "");
+        if (byDescription !== 0)
+            return byDescription;
+        return JSON.stringify(a.recurrence ?? {}).localeCompare(JSON.stringify(b.recurrence ?? {}));
+    });
+    return normalized;
+}
+function normalizeFiles(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    return values
         .map((value) => ({
         path: normalizePathValue(value.path),
         scope: value.scope,
         note: value.note?.trim() || undefined,
-    }))
+    }));
+}
+function normalizeTestRunSummaries(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const normalized = values
+        .map((value) => {
+        const runId = typeof value.run_id === "string" ? value.run_id.trim() : "";
+        const kind = value.kind === "test" || value.kind === "test-all" ? value.kind : "test";
+        const status = value.status === "passed" || value.status === "failed" || value.status === "stopped" || value.status === "canceled"
+            ? value.status
+            : "failed";
+        const startedAt = typeof value.started_at === "string" ? value.started_at : "";
+        const finishedAt = typeof value.finished_at === "string" ? value.finished_at : "";
+        const recordedAt = typeof value.recorded_at === "string" ? value.recorded_at : "";
+        const passed = typeof value.passed === "number" && Number.isFinite(value.passed) ? Math.max(0, Math.floor(value.passed)) : 0;
+        const failed = typeof value.failed === "number" && Number.isFinite(value.failed) ? Math.max(0, Math.floor(value.failed)) : 0;
+        const skipped = typeof value.skipped === "number" && Number.isFinite(value.skipped) ? Math.max(0, Math.floor(value.skipped)) : 0;
+        return {
+            run_id: runId,
+            kind,
+            status,
+            started_at: startedAt,
+            finished_at: finishedAt,
+            recorded_at: recordedAt,
+            attempt: typeof value.attempt === "number" && Number.isFinite(value.attempt) && value.attempt >= 1
+                ? Math.floor(value.attempt)
+                : undefined,
+            resumed_from: value.resumed_from?.trim() || undefined,
+            passed,
+            failed,
+            skipped,
+            items: typeof value.items === "number" && Number.isFinite(value.items) && value.items >= 0
+                ? Math.floor(value.items)
+                : undefined,
+            linked_tests: typeof value.linked_tests === "number" && Number.isFinite(value.linked_tests) && value.linked_tests >= 0
+                ? Math.floor(value.linked_tests)
+                : undefined,
+            fail_on_skipped_triggered: value.fail_on_skipped_triggered === true ? true : undefined,
+        };
+    })
+        .filter((value) => value.run_id.length > 0 && value.started_at.length > 0 && value.finished_at.length > 0 && value.recorded_at.length > 0)
         .sort((a, b) => {
-        const byScope = a.scope.localeCompare(b.scope);
-        if (byScope !== 0)
-            return byScope;
-        const byPath = a.path.localeCompare(b.path);
-        if (byPath !== 0)
-            return byPath;
-        return (a.note ?? "").localeCompare(b.note ?? "");
+        const byRecorded = compareTimestampStrings(a.recorded_at, b.recorded_at);
+        if (byRecorded !== 0)
+            return byRecorded;
+        const byRunId = a.run_id.localeCompare(b.run_id);
+        if (byRunId !== 0)
+            return byRunId;
+        return a.kind.localeCompare(b.kind);
     });
+    return normalized.length > 0 ? normalized : undefined;
 }
 function sortTests(values) {
     if (!values || values.length === 0)
@@ -155,6 +457,52 @@ function sortTests(values) {
         path: value.path ? normalizePathValue(value.path) : undefined,
         scope: value.scope,
         timeout_seconds: value.timeout_seconds,
+        pm_context_mode: (() => {
+            const normalized = value.pm_context_mode?.trim().toLowerCase();
+            if (!normalized || !LINKED_TEST_PM_CONTEXT_MODE_VALUES.has(normalized)) {
+                return undefined;
+            }
+            return normalized;
+        })(),
+        env_set: value.env_set
+            ? Object.fromEntries(Object.entries(value.env_set)
+                .map(([key, envValue]) => [key.trim(), String(envValue).trim()])
+                .filter(([key, envValue]) => key.length > 0 && envValue.length > 0)
+                .sort(([left], [right]) => left.localeCompare(right)))
+            : undefined,
+        env_clear: value.env_clear
+            ? [...new Set(value.env_clear.map((entry) => entry.trim()).filter((entry) => entry.length > 0))].sort((a, b) => a.localeCompare(b))
+            : undefined,
+        shared_host_safe: value.shared_host_safe === true ? true : undefined,
+        assert_stdout_contains: value.assert_stdout_contains
+            ? [...new Set(value.assert_stdout_contains.map((entry) => entry.trim()).filter((entry) => entry.length > 0))].sort((a, b) => a.localeCompare(b))
+            : undefined,
+        assert_stdout_regex: value.assert_stdout_regex
+            ? [...new Set(value.assert_stdout_regex.map((entry) => entry.trim()).filter((entry) => entry.length > 0))].sort((a, b) => a.localeCompare(b))
+            : undefined,
+        assert_stderr_contains: value.assert_stderr_contains
+            ? [...new Set(value.assert_stderr_contains.map((entry) => entry.trim()).filter((entry) => entry.length > 0))].sort((a, b) => a.localeCompare(b))
+            : undefined,
+        assert_stderr_regex: value.assert_stderr_regex
+            ? [...new Set(value.assert_stderr_regex.map((entry) => entry.trim()).filter((entry) => entry.length > 0))].sort((a, b) => a.localeCompare(b))
+            : undefined,
+        assert_stdout_min_lines: typeof value.assert_stdout_min_lines === "number" &&
+            Number.isFinite(value.assert_stdout_min_lines) &&
+            value.assert_stdout_min_lines >= 0
+            ? Math.floor(value.assert_stdout_min_lines)
+            : undefined,
+        assert_json_field_equals: value.assert_json_field_equals
+            ? Object.fromEntries(Object.entries(value.assert_json_field_equals)
+                .map(([key, expectedValue]) => [key.trim(), String(expectedValue).trim()])
+                .filter(([key, expectedValue]) => key.length > 0 && expectedValue.length > 0)
+                .sort(([left], [right]) => left.localeCompare(right)))
+            : undefined,
+        assert_json_field_gte: value.assert_json_field_gte
+            ? Object.fromEntries(Object.entries(value.assert_json_field_gte)
+                .map(([key, expectedValue]) => [key.trim(), Number(expectedValue)])
+                .filter(([key, expectedValue]) => key.length > 0 && Number.isFinite(expectedValue))
+                .sort(([left], [right]) => left.localeCompare(right)))
+            : undefined,
         note: value.note?.trim() || undefined,
     }))
         .sort((a, b) => {
@@ -170,6 +518,39 @@ function sortTests(values) {
         const byTimeout = (a.timeout_seconds ?? 0) - (b.timeout_seconds ?? 0);
         if (byTimeout !== 0)
             return byTimeout;
+        const byPmContext = (a.pm_context_mode ?? "").localeCompare(b.pm_context_mode ?? "");
+        if (byPmContext !== 0)
+            return byPmContext;
+        const bySharedHostSafe = Number(Boolean(a.shared_host_safe)) - Number(Boolean(b.shared_host_safe));
+        if (bySharedHostSafe !== 0)
+            return bySharedHostSafe;
+        const byEnvClear = JSON.stringify(a.env_clear ?? []).localeCompare(JSON.stringify(b.env_clear ?? []));
+        if (byEnvClear !== 0)
+            return byEnvClear;
+        const byEnvSet = JSON.stringify(a.env_set ?? {}).localeCompare(JSON.stringify(b.env_set ?? {}));
+        if (byEnvSet !== 0)
+            return byEnvSet;
+        const byStdoutContains = JSON.stringify(a.assert_stdout_contains ?? []).localeCompare(JSON.stringify(b.assert_stdout_contains ?? []));
+        if (byStdoutContains !== 0)
+            return byStdoutContains;
+        const byStdoutRegex = JSON.stringify(a.assert_stdout_regex ?? []).localeCompare(JSON.stringify(b.assert_stdout_regex ?? []));
+        if (byStdoutRegex !== 0)
+            return byStdoutRegex;
+        const byStderrContains = JSON.stringify(a.assert_stderr_contains ?? []).localeCompare(JSON.stringify(b.assert_stderr_contains ?? []));
+        if (byStderrContains !== 0)
+            return byStderrContains;
+        const byStderrRegex = JSON.stringify(a.assert_stderr_regex ?? []).localeCompare(JSON.stringify(b.assert_stderr_regex ?? []));
+        if (byStderrRegex !== 0)
+            return byStderrRegex;
+        const byStdoutMinLines = (a.assert_stdout_min_lines ?? 0) - (b.assert_stdout_min_lines ?? 0);
+        if (byStdoutMinLines !== 0)
+            return byStdoutMinLines;
+        const byJsonFieldEquals = JSON.stringify(a.assert_json_field_equals ?? {}).localeCompare(JSON.stringify(b.assert_json_field_equals ?? {}));
+        if (byJsonFieldEquals !== 0)
+            return byJsonFieldEquals;
+        const byJsonFieldGte = JSON.stringify(a.assert_json_field_gte ?? {}).localeCompare(JSON.stringify(b.assert_json_field_gte ?? {}));
+        if (byJsonFieldGte !== 0)
+            return byJsonFieldGte;
         return (a.note ?? "").localeCompare(b.note ?? "");
     });
 }
@@ -192,6 +573,19 @@ function sortDocs(values) {
         return (a.note ?? "").localeCompare(b.note ?? "");
     });
 }
+function normalizeTypeOptions(values) {
+    if (!values) {
+        return undefined;
+    }
+    const normalizedEntries = Object.entries(values)
+        .map(([key, value]) => [key.trim(), value.trim()])
+        .filter(([key, value]) => key.length > 0 && value.length > 0)
+        .sort((left, right) => left[0].localeCompare(right[0]));
+    if (normalizedEntries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(normalizedEntries);
+}
 function normalizeBody(body) {
     return body.replace(/^\n+/, "").replace(/\s+$/, "");
 }
@@ -224,7 +618,9 @@ function normalizeSeverityValue(value) {
     }
     return undefined;
 }
-export function normalizeFrontMatter(frontMatter) {
+export function normalizeFrontMatter(frontMatter, options = {}) {
+    const runtimeContext = resolveRuntimeSchemaValidationContext(options);
+    const normalizedStatus = normalizeStatusInput(frontMatter.status, runtimeContext?.statusRegistry) ?? frontMatter.status;
     const tags = Array.from(new Set(frontMatter.tags.map((tag) => tag.trim().toLowerCase()).filter(Boolean))).sort((a, b) => a.localeCompare(b));
     const normalized = {
         id: frontMatter.id,
@@ -232,7 +628,8 @@ export function normalizeFrontMatter(frontMatter) {
         description: frontMatter.description,
         type: frontMatter.type,
         source_type: frontMatter.source_type?.trim() || undefined,
-        status: frontMatter.status,
+        type_options: normalizeTypeOptions(frontMatter.type_options),
+        status: normalizedStatus,
         priority: frontMatter.priority,
         tags,
         created_at: frontMatter.created_at,
@@ -241,10 +638,13 @@ export function normalizeFrontMatter(frontMatter) {
         comments: sortLogValues(frontMatter.comments),
         notes: sortLogValues(frontMatter.notes),
         learnings: sortLogValues(frontMatter.learnings),
-        files: sortFiles(frontMatter.files),
+        files: normalizeFiles(frontMatter.files),
         tests: sortTests(frontMatter.tests),
+        test_runs: normalizeTestRunSummaries(frontMatter.test_runs),
         docs: sortDocs(frontMatter.docs),
         deadline: frontMatter.deadline || undefined,
+        reminders: sortReminders(frontMatter.reminders),
+        events: sortEvents(frontMatter.events),
         closed_at: frontMatter.closed_at || undefined,
         assignee: frontMatter.assignee?.trim() || undefined,
         source_owner: frontMatter.source_owner?.trim() || undefined,
@@ -284,6 +684,36 @@ export function normalizeFrontMatter(frontMatter) {
         customer_impact: frontMatter.customer_impact?.trim() || undefined,
         close_reason: frontMatter.close_reason || undefined,
     };
+    const sourceRecord = frontMatter;
+    for (const [key, value] of Object.entries(sourceRecord)) {
+        if (Object.prototype.hasOwnProperty.call(normalized, key) || value === undefined) {
+            continue;
+        }
+        normalized[key] = value;
+    }
+    if (runtimeContext?.fieldRegistry) {
+        for (const definition of runtimeContext.fieldRegistry.definitions) {
+            const currentValue = normalized[definition.front_matter_key];
+            if (currentValue === undefined) {
+                continue;
+            }
+            normalized[definition.front_matter_key] = coerceRuntimeFieldValue(definition, currentValue, `metadata field "${definition.front_matter_key}"`);
+        }
+    }
+    if (runtimeContext && runtimeContext.unknownFieldPolicy !== "allow") {
+        const knownKeys = new Set(STATIC_FRONT_MATTER_FIELD_SET);
+        for (const definition of runtimeContext.fieldRegistry?.definitions ?? []) {
+            knownKeys.add(definition.front_matter_key);
+        }
+        const unknownKeys = Object.keys(normalized)
+            .filter((key) => !knownKeys.has(key))
+            .sort((left, right) => left.localeCompare(right));
+        if (unknownKeys.length > 0) {
+            if (runtimeContext.unknownFieldPolicy === "reject") {
+                validationError(`unknown schema fields are not allowed: ${unknownKeys.join(", ")}`);
+            }
+        }
+    }
     for (const [key, value] of Object.entries(normalized)) {
         if (value === undefined) {
             delete normalized[key];
@@ -343,7 +773,7 @@ export function splitFrontMatter(content) {
     const body = content.slice(end + 1).replace(/^\r?\n+/, "");
     return { frontMatter, body };
 }
-export function parseItemDocument(content) {
+function parseJsonMarkdownItemDocument(content, runtimeContext, options = {}) {
     const { frontMatter, body } = splitFrontMatter(content);
     if (!frontMatter) {
         const trimmed = content.trimStart();
@@ -359,14 +789,40 @@ export function parseItemDocument(content) {
     catch {
         validationError("JSON front matter is not valid JSON");
     }
-    assertValidFrontMatter(parsed);
+    assertValidFrontMatter(parsed, runtimeContext);
     return {
-        front_matter: normalizeFrontMatter(parsed),
+        front_matter: normalizeFrontMatter(parsed, options),
         body: normalizeBody(body),
     };
 }
-export function serializeItemDocument(document) {
-    const normalizedFrontMatter = normalizeFrontMatter(document.front_matter);
+function parseToonItemDocument(content, runtimeContext, options = {}) {
+    let parsed;
+    try {
+        parsed = decodeToon(content);
+    }
+    catch {
+        validationError("TOON item document is not valid TOON");
+    }
+    assertFrontMatterCondition(typeof parsed === "object" && parsed !== null && !Array.isArray(parsed), "TOON item document must be an object");
+    const record = parsed;
+    if (Object.prototype.hasOwnProperty.call(record, "front_matter")) {
+        assertValidFrontMatter(record.front_matter, runtimeContext);
+        assertFrontMatterCondition(record.body === undefined || typeof record.body === "string", "TOON item document body must be a string");
+        return {
+            front_matter: normalizeFrontMatter(record.front_matter, options),
+            body: normalizeBody(typeof record.body === "string" ? record.body : ""),
+        };
+    }
+    const { body, ...frontMatterRecord } = record;
+    assertFrontMatterCondition(body === undefined || typeof body === "string", "TOON item document body must be a string");
+    assertValidFrontMatter(frontMatterRecord, runtimeContext);
+    return {
+        front_matter: normalizeFrontMatter(frontMatterRecord, options),
+        body: normalizeBody(typeof body === "string" ? body : ""),
+    };
+}
+function serializeJsonMarkdownItemDocument(document, options = {}) {
+    const normalizedFrontMatter = normalizeFrontMatter(document.front_matter, options);
     const orderedFrontMatter = orderFrontMatter(normalizedFrontMatter);
     const serializedFrontMatter = JSON.stringify(orderedFrontMatter, null, 2);
     const normalizedBody = normalizeBody(document.body ?? "");
@@ -375,9 +831,36 @@ export function serializeItemDocument(document) {
     }
     return `${serializedFrontMatter}\n\n${normalizedBody}\n`;
 }
-export function canonicalDocument(document) {
+function serializeToonItemDocument(document, options = {}) {
+    const normalizedFrontMatter = normalizeFrontMatter(document.front_matter, options);
+    const orderedFrontMatter = orderFrontMatter(normalizedFrontMatter);
+    const normalizedBody = normalizeBody(document.body ?? "");
+    return `${encodeToon({ ...orderedFrontMatter, body: normalizedBody })}\n`;
+}
+export function parseItemDocument(content, options = {}) {
+    const conflictMarker = findFirstMergeConflictMarker(content);
+    if (conflictMarker) {
+        throw new PmCliError(`Merge conflict markers detected in item document at line ${conflictMarker.line} (${conflictMarker.marker}). Resolve <<<<<<< ======= >>>>>>> markers and retry.`, EXIT_CODE.GENERIC_FAILURE, {
+            code: "merge_conflict_markers_detected",
+            required: "Resolve merge-conflict markers in the item file before parsing or mutation commands.",
+            why: "Partially merged documents can corrupt item metadata and history integrity.",
+            examples: ["git status", "git add <resolved-file> && git commit"],
+            nextSteps: ["Resolve conflicts, save the file, then rerun the pm command."],
+        });
+    }
+    const format = options.format ?? "json_markdown";
+    const runtimeContext = resolveRuntimeSchemaValidationContext(options);
+    return format === "toon"
+        ? parseToonItemDocument(content, runtimeContext, options)
+        : parseJsonMarkdownItemDocument(content, runtimeContext, options);
+}
+export function serializeItemDocument(document, options = {}) {
+    const format = options.format ?? "json_markdown";
+    return format === "toon" ? serializeToonItemDocument(document, options) : serializeJsonMarkdownItemDocument(document, options);
+}
+export function canonicalDocument(document, options = {}) {
     return {
-        front_matter: normalizeFrontMatter(document.front_matter),
+        front_matter: normalizeFrontMatter(document.front_matter, options),
         body: normalizeBody(document.body ?? ""),
     };
 }