@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.20"
+    "version": "2026.8.22"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.20",
+      "version": "2026.8.22",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 2026.8.22 - 2026-08-22
+
+### Fixed
+
+- GH-1078: Complete-list certification accepts absent or contradictory truth receipts and emits stale recovery ([pm-gh1078](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1078.toon))
+- GH-1076: read-only duplicates rejects universal JSON output controls ([pm-gh1076](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1076.toon))
+- GH-1074: package doctor cannot distinguish a safe declining service override from a global interceptor ([pm-gh1074](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1074.toon))
+- GH-1073: pm init accepts a whitespace id prefix that makes later creates fail ([pm-gh1073](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1073.toon))
+- GH-1075: Windows Node 24 nightly validation failed at main 3e7ac007 ([pm-gh1075](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1075.toon))
+- The child hierarchy kind has an unenforced direction and cardinality: 7 of 15 rows are inverted against the registry's own declaration and no channel, validator, or audit finding notices ([pm-vk7zek](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-vk7zek.toon))
+- Hierarchy-canonicalizing dependency kinds bypass every cycle detector: mutual child_of edges leave the graph provably inconsistent while validate, health, and graph analyze all report acyclic ([pm-rggtvd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-rggtvd.toon))
+
+### Security
+
+- GH-1072: pm install leaks user allow-scripts config into isolated package installs ([pm-gh1072](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1072.toon))
+
+## 2026.8.21 - 2026-08-21
+
+### Added
+
+- Prose-asserted relationships are unmeasured: 1,750 identifier pairs named in item text carry no edge in any direction, and nothing counts the gap ([pm-ob9z4y](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-ob9z4y.toon))
+
+### Changed
+
+- Provide consistent tracker preflight and executable recovery across SDK, CLI, and MCP ([pm-6qiwan](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-6qiwan.toon))
+
+### Fixed
+
+- The blocks ceiling counts fabricated and evidence-cited ordering edges identically, so the historical ordering reconstruction another item mandates cannot land ([pm-c90tfh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-c90tfh.toon))
+- The dependency remove flag accepts a value its own add flag refuses and reports success on a zero-match, so a mistyped graph repair exits 0 having changed nothing ([pm-gos426](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gos426.toon))
+- All four graph traversal verbs reject the semantic edge kinds the ontology exists to express, so 'what implements this milestone' returns the ordering-kind answer with no sign a semantic one exists ([pm-3dyec2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3dyec2.toon))
+- Typed-outcome reachability admits three of ten edge kinds, so the four semantic kinds the ontology exists to express contribute nothing to the invariant they were minted to satisfy ([pm-ayg31c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ayg31c.toon))
+- The graph audit raises duplicate dependency rows at warning severity and the only remediation available deletes every copy, so collapsing a duplicate means briefly destroying a real edge ([pm-flnefm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-flnefm.toon))
+
+### Other
+
+- ADR: Ordering assurance partitions evidence-cited blocks from uncited blocks ([pm-jhpby4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-jhpby4.toon))
+
 ## 2026.8.20 - 2026-08-20
 
 ### Added

package/dist/cli/error-guidance.d.ts

@@ -4,6 +4,7 @@
  * Provides CLI runtime support for Error Guidance.
  */
 import { type PmCliErrorContext, type PmCliErrorRecoveryPayload } from "../sdk/runtime-primitives.js";
+import { type PmDiagnosticOutputReceipt, type PmProjectedDiagnostic } from "../sdk/cli-contracts/agent-output-contracts.js";
 interface GuidanceMessage {
     code: string;
     type: string;
@@ -14,6 +15,10 @@ interface GuidanceMessage {
     examples?: string[];
     nextSteps?: string[];
     verificationErrors?: string[];
+    flag?: string;
+    value?: string;
+    unmatchedSelectors?: NonNullable<PmCliErrorContext["unmatched_selectors"]>;
+    availableDependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     recovery?: PmCliErrorRecoveryPayload;
 }
 /** Documents the json error envelope payload exchanged by command, SDK, and package integrations. */
@@ -38,11 +43,23 @@ export interface JsonErrorEnvelope {
     next_steps?: string[];
     /** Exact integrity verifier findings that caused the operation to refuse. */
     verification_errors?: string[];
+    /** CLI flag whose supplied value violated a shared mutation grammar. */
+    flag?: string;
+    /** Supplied scalar value that violated a shared mutation grammar. */
+    value?: string;
+    /** Dependency selectors that matched no stored edge. */
+    unmatched_selectors?: NonNullable<PmCliErrorContext["unmatched_selectors"]>;
+    /** Compact stored dependency identities available when a removal failed. */
+    available_dependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     /** Value that configures or reports recovery for this contract. */
     recovery?: PmCliErrorRecoveryPayload;
+    /** Binding output-budget receipt for this diagnostic. */
+    diagnostic_output?: PmDiagnosticOutputReceipt;
 }
+/** Error envelope after deterministic budget projection. */
+export type ProjectedJsonErrorEnvelope = PmProjectedDiagnostic<JsonErrorEnvelope>;
 /** Compact an error envelope to fields that change the caller's next action. */
-export declare function projectLeanErrorEnvelope(envelope: JsonErrorEnvelope): Omit<JsonErrorEnvelope, "required" | "why" | "title">;
+export declare function projectLeanErrorEnvelope(envelope: ProjectedJsonErrorEnvelope): ProjectedJsonErrorEnvelope;
 /** Documents the error classification payload exchanged by command, SDK, and package integrations. */
 export interface ErrorClassification {
     /** Schema type that determines the shape and validation rules for this value. */
@@ -63,6 +80,14 @@ export interface ErrorClassification {
     next_steps?: string[];
     /** Exact integrity verifier findings that caused the operation to refuse. */
     verification_errors?: string[];
+    /** CLI flag whose supplied value violated a shared mutation grammar. */
+    flag?: string;
+    /** Supplied scalar value that violated a shared mutation grammar. */
+    value?: string;
+    /** Dependency selectors that matched no stored edge. */
+    unmatched_selectors?: NonNullable<PmCliErrorContext["unmatched_selectors"]>;
+    /** Compact stored dependency identities available when a removal failed. */
+    available_dependencies?: NonNullable<PmCliErrorContext["available_dependencies"]>;
     /** Value that configures or reports recovery for this contract. */
     recovery?: PmCliErrorRecoveryPayload;
 }
@@ -129,15 +154,15 @@ export declare function formatPmCliErrorForDisplay(rawMessage: string, context?:
 /** Implements classify pm cli error for the public runtime surface of this module. */
 export declare function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification;
 /** Implements format pm cli error for json for the public runtime surface of this module. */
-export declare function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope;
+export declare function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): ProjectedJsonErrorEnvelope;
 /** Implements format commander error for display for the public runtime surface of this module. */
 export declare function formatCommanderErrorForDisplay(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): string;
 /** Implements classify commander error for the public runtime surface of this module. */
 export declare function classifyCommanderError(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): ErrorClassification;
 /** Implements format commander error for json for the public runtime surface of this module. */
-export declare function formatCommanderErrorForJson(rawMessage: string, commandName: string | undefined, allowedTypes: string, exitCode: number, context?: CommanderGuidanceContext): JsonErrorEnvelope;
+export declare function formatCommanderErrorForJson(rawMessage: string, commandName: string | undefined, allowedTypes: string, exitCode: number, context?: CommanderGuidanceContext): ProjectedJsonErrorEnvelope;
 /** Implements format unknown error for json for the public runtime surface of this module. */
-export declare function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope;
+export declare function formatUnknownErrorForJson(rawMessage: string, exitCode: number): ProjectedJsonErrorEnvelope;
 /** Implements classify unknown error for the public runtime surface of this module. */
 export declare function classifyUnknownError(rawMessage: string): ErrorClassification;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */

package/dist/cli/error-guidance.js

@@ -1,11 +1,12 @@
 
-!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]="367d9302-9e1e-5813-a913-e4e87f34d8b9")}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]="72da6986-67d5-5adf-8e63-4f654d9ec7dd")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
+import { projectPmDiagnosticOutput, projectPmDiagnosticText, } from "../sdk/cli-contracts/agent-output-contracts.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
 /** Compact an error envelope to fields that change the caller's next action. */
 export function projectLeanErrorEnvelope(envelope) {
-    const { required: _required, why: _why, title: _title, ...actionable } = envelope;
+    const { why: _why, title: _title, ...actionable } = envelope;
     return actionable;
 }
 // JSON/classification payloads are consumed heavily by agents; suppress common
@@ -249,12 +250,14 @@ export function renderGuidanceMessage(message) {
     const lines = [
         `Error: ${message.title}`,
         "",
-        "What happened:",
-        `  ${message.happened}`,
-        "",
         "What is required:",
         `  ${message.required}`,
     ];
+    if (message.nextSteps && message.nextSteps.length > 0) {
+        lines.push("");
+        lines.push(...renderList("Next steps:", message.nextSteps));
+    }
+    lines.push("", "What happened:", `  ${message.happened}`);
     if (message.why) {
         lines.push("", "Why:");
         lines.push(`  ${message.why}`);
@@ -263,10 +266,6 @@ export function renderGuidanceMessage(message) {
         lines.push("");
         lines.push(...renderList("Examples:", message.examples));
     }
-    if (message.nextSteps && message.nextSteps.length > 0) {
-        lines.push("");
-        lines.push(...renderList("Next steps:", message.nextSteps));
-    }
     if (message.verificationErrors && message.verificationErrors.length > 0) {
         lines.push("");
         lines.push(...renderList("Verification errors:", message.verificationErrors));
@@ -278,15 +277,8 @@ export function renderGuidanceMessage(message) {
     }
     return lines.join("\n");
 }
-function guidanceToJsonEnvelope(message, exitCode) {
-    const payload = {
-        type: message.type,
-        code: message.code,
-        title: message.title,
-        detail: message.happened,
-        required: message.required,
-        exit_code: exitCode,
-    };
+/** Attach optional actionable fields shared by JSON and classification envelopes. */
+function attachStructuredGuidanceDetails(payload, message) {
     if (includeWhyInStructuredGuidance(message)) {
         payload.why = message.why;
     }
@@ -299,35 +291,37 @@ function guidanceToJsonEnvelope(message, exitCode) {
     if (message.verificationErrors && message.verificationErrors.length > 0) {
         payload.verification_errors = message.verificationErrors;
     }
+    if (message.flag !== undefined)
+        payload.flag = message.flag;
+    if (message.value !== undefined)
+        payload.value = message.value;
+    if (message.unmatchedSelectors !== undefined)
+        payload.unmatched_selectors = message.unmatchedSelectors;
+    if (message.availableDependencies !== undefined)
+        payload.available_dependencies = message.availableDependencies;
     if (message.recovery) {
         payload.recovery = message.recovery;
     }
     return payload;
 }
+function guidanceToJsonEnvelope(message, exitCode) {
+    return attachStructuredGuidanceDetails({
+        type: message.type,
+        code: message.code,
+        title: message.title,
+        detail: message.happened,
+        required: message.required,
+        exit_code: exitCode,
+    }, message);
+}
 function guidanceToClassification(message) {
-    const payload = {
+    return attachStructuredGuidanceDetails({
         type: message.type,
         code: message.code,
         title: message.title,
         detail: message.happened,
         required: message.required,
-    };
-    if (includeWhyInStructuredGuidance(message)) {
-        payload.why = message.why;
-    }
-    if (message.examples && message.examples.length > 0) {
-        payload.examples = message.examples;
-    }
-    if (message.nextSteps && message.nextSteps.length > 0) {
-        payload.next_steps = message.nextSteps;
-    }
-    if (message.verificationErrors && message.verificationErrors.length > 0) {
-        payload.verification_errors = message.verificationErrors;
-    }
-    if (message.recovery) {
-        payload.recovery = message.recovery;
-    }
-    return payload;
+    }, message);
 }
 function normalizeMessage(message) {
     return message.replace(/\(outputHelp\)/g, "").trim();
@@ -435,11 +429,15 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
         examples,
         nextSteps,
         verificationErrors,
+        flag: context.flag,
+        value: context.value,
+        unmatchedSelectors: context.unmatched_selectors,
+        availableDependencies: context.available_dependencies,
         recovery,
     };
 }
 function buildTrackerNotInitializedGuidance(rawMessage, message, context) {
-    const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\. Run pm init first\.$/);
+    const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\. (?:Run pm init first|Tracker root does not exist\. Run pm init first)\.$/);
     if (!trackerNotInitialized) {
         return null;
     }
@@ -1165,7 +1163,8 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
 }
 /** Implements format pm cli error for display for the public runtime surface of this module. */
 export function formatPmCliErrorForDisplay(rawMessage, context) {
-    return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));
+    const guidance = buildPmCliErrorGuidance(rawMessage, context);
+    return projectPmDiagnosticText(renderGuidanceMessage(guidance), guidance.required).output;
 }
 /** Implements classify pm cli error for the public runtime surface of this module. */
 export function classifyPmCliError(rawMessage, context) {
@@ -1173,11 +1172,12 @@ export function classifyPmCliError(rawMessage, context) {
 }
 /** Implements format pm cli error for json for the public runtime surface of this module. */
 export function formatPmCliErrorForJson(rawMessage, exitCode, context) {
-    return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);
+    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode));
 }
 /** Implements format commander error for display for the public runtime surface of this module. */
 export function formatCommanderErrorForDisplay(rawMessage, commandName, allowedTypes, context) {
-    return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));
+    const guidance = buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context);
+    return projectPmDiagnosticText(renderGuidanceMessage(guidance), guidance.required).output;
 }
 /** Implements classify commander error for the public runtime surface of this module. */
 export function classifyCommanderError(rawMessage, commandName, allowedTypes, context) {
@@ -1185,12 +1185,12 @@ export function classifyCommanderError(rawMessage, commandName, allowedTypes, co
 }
 /** Implements format commander error for json for the public runtime surface of this module. */
 export function formatCommanderErrorForJson(rawMessage, commandName, allowedTypes, exitCode, context) {
-    return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);
+    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode));
 }
 /** Implements format unknown error for json for the public runtime surface of this module. */
 export function formatUnknownErrorForJson(rawMessage, exitCode) {
     const guidance = buildUnknownErrorGuidance(rawMessage);
-    return guidanceToJsonEnvelope(guidance, exitCode);
+    return projectPmDiagnosticOutput(guidanceToJsonEnvelope(guidance, exitCode));
 }
 function buildUnknownErrorGuidance(rawMessage) {
     const message = normalizeMessage(rawMessage);
@@ -1241,4 +1241,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=367d9302-9e1e-5813-a913-e4e87f34d8b9
+//# debugId=72da6986-67d5-5adf-8e63-4f654d9ec7dd

package/dist/cli/main.d.ts

@@ -11,6 +11,8 @@ import { type ExtensionCommandHelpDescriptor } from "./extension-command-help.js
 import { normalizeBootstrapInvocation } from "./bootstrap-args.js";
 import { type MandatoryMigrationBlocker } from "./migration-gates.js";
 import { resolveUnknownCommanderToken } from "./commander-usage.js";
+/** Record the exact compatibility flags present in the raw CLI invocation. */
+declare function recordCliReadOutputInvocationProvenance(actionCommand: Command, commandPath: string, commandOptions: Record<string, unknown>): void;
 declare function setActiveExtensionHookContextForTest(context: ActiveExtensionHookContext<MandatoryMigrationBlocker> | null): void;
 declare function setActiveRuntimeExtensionCommandDescriptorsForTest(descriptors: Map<string, ExtensionCommandHelpDescriptor>): void;
 interface RuntimeExtensionSnapshot {
@@ -292,6 +294,7 @@ export declare const _testOnly: {
     readRecordBoolean: typeof readRecordBoolean;
     readRecordNumber: typeof readRecordNumber;
     readRecordString: typeof readRecordString;
+    recordCliReadOutputInvocationProvenance: typeof recordCliReadOutputInvocationProvenance;
     registerDynamicExtensionCommandPaths: typeof registerDynamicExtensionCommandPaths;
     registerRuntimeSchemaFieldFlags: typeof registerRuntimeSchemaFieldFlags;
     resolveCoreCommandRegistrationSelection: typeof resolveCoreCommandRegistrationSelection;

package/dist/cli/main.js

@@ -3,7 +3,7 @@
  * @module cli/main
  */
 
-!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]="27eeca2d-756c-539b-a0d4-d64516ee4aa6")}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]="5a349bce-a08d-5ff6-870a-3ec38843b512")}catch(e){}}();
 import { Command } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
@@ -27,10 +27,38 @@ import { loadExtensionRecoveryFailures, loadUnknownCommandRecoveryFailures } fro
 import { maybeRenderBootstrapJsonHelp, attachCreateUpdatePolicyHelpText } from "./help-json-payload.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { runWithDiscoveredContextIntentContracts } from "../sdk/context-intent-runtime.js";
-import { applyReadOutputIncludeModes, validateReadOutputOptions } from "../sdk/read-output-contracts.js";
+import { PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputIncludeModes, readOutputIncludeModeOptions, resolveReadOutputSurface, validateReadOutputOptions, } from "../sdk/read-output-contracts.js";
 import { loadContextIntentSnapshotForInvocation } from "./context-intent-invocation.js";
 import { isPmSuccessfulExitCode } from "../sdk/cli-contracts/command-exit-contracts.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
+const READ_OUTPUT_INVOCATION_PROVENANCE = Symbol.for("pm.readOutputInvocationProvenance");
+/** Carry private read-output provenance across Commander's option rebuilds. */
+function copyReadOutputInvocationProvenance(source, target) {
+    const provenance = Reflect.get(source, READ_OUTPUT_INVOCATION_PROVENANCE);
+    if (provenance !== undefined) {
+        Reflect.set(target, READ_OUTPUT_INVOCATION_PROVENANCE, provenance);
+    }
+}
+/** Record the exact compatibility flags present in the raw CLI invocation. */
+function recordCliReadOutputInvocationProvenance(actionCommand, commandPath, commandOptions) {
+    const surface = resolveReadOutputSurface(commandPath, commandOptions);
+    if (!surface)
+        return;
+    let rootCommand = actionCommand;
+    while (rootCommand.parent)
+        rootCommand = rootCommand.parent;
+    const rawArgs = rootCommand.rawArgs;
+    const providedFlags = new Set(extractProvidedOptionFlags(rawArgs.slice(2)));
+    const contract = PM_READ_OUTPUT_SURFACE_CONTRACTS.find((candidate) => candidate.command === surface);
+    const explicitLegacyAliases = Object.values(contract.dimensions).flatMap((dimension) => dimension.legacy_aliases.flatMap((alias) => providedFlags.has(alias.flag) ? [alias.flag] : []));
+    const previous = Reflect.get(commandOptions, READ_OUTPUT_INVOCATION_PROVENANCE);
+    Reflect.set(commandOptions, READ_OUTPUT_INVOCATION_PROVENANCE, {
+        canonical_include_modes: previous?.canonical_include_modes ?? [],
+        explicit_legacy_aliases: explicitLegacyAliases,
+        cli_invocation_observed: true,
+    });
+    copyReadOutputInvocationProvenance(commandOptions, actionCommand);
+}
 function resolvePmPackageRoot() {
     return resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
 }
@@ -512,15 +540,18 @@ async function handleGenericRunPmCliError(params) {
  * command computes its rows, so it cannot be resolved by the output layer.
  */
 function forwardReadOutputIncludeModes(actionCommand, commandPath, globalOptions, commandOptions) {
+    recordCliReadOutputInvocationProvenance(actionCommand, commandPath, commandOptions);
     const requested = globalOptions.outputInclude;
     if (requested === undefined)
         return;
-    const modeOptions = {};
-    const { selectors, modes } = applyReadOutputIncludeModes(commandPath, requested, modeOptions);
+    const { selectors, modes } = applyReadOutputIncludeModes(commandPath, requested, commandOptions);
     if (modes.length === 0)
         return;
-    for (const [key, value] of Object.entries(modeOptions)) {
-        commandOptions[key] = value;
+    copyReadOutputInvocationProvenance(commandOptions, actionCommand);
+    const modeOptions = readOutputIncludeModeOptions(commandPath);
+    for (const mode of modes) {
+        const key = modeOptions.get(mode);
+        const value = commandOptions[key];
         actionCommand.setOptionValueWithSource(key, value, "cli");
     }
     const residual = selectors.length > 0 ? selectors.join(",") : undefined;
@@ -540,6 +571,7 @@ function forwardReadOutputIncludeModes(actionCommand, commandPath, globalOptions
 function extractCommandScopedOptions(command, commandArgs, extensionFlagDefinitions = []) {
     const allOptions = command.optsWithGlobals();
     const scoped = { ...allOptions };
+    copyReadOutputInvocationProvenance(command, scoped);
     delete scoped.json;
     delete scoped.quiet;
     delete scoped.path;
@@ -2493,6 +2525,7 @@ export const _testOnly = {
     readRecordBoolean,
     readRecordNumber,
     readRecordString,
+    recordCliReadOutputInvocationProvenance,
     registerDynamicExtensionCommandPaths,
     registerRuntimeSchemaFieldFlags,
     resolveCoreCommandRegistrationSelection,
@@ -2516,4 +2549,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=27eeca2d-756c-539b-a0d4-d64516ee4aa6
+//# debugId=5a349bce-a08d-5ff6-870a-3ec38843b512