@unbrained/pm-cli 2026.8.6 → 2026.8.8

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.6"
+    "version": "2026.8.8"
   },
   "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.6",
+      "version": "2026.8.8",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 2026.8.8 - 2026-08-08
+
+### Added
+
+- The CLI has 195 error codes and contracts none of them: the surface agents read when they are wrong is the only one with no enumeration, no stability promise, and no gate ([pm-x4nn3z](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-x4nn3z.toon))
+
+### Fixed
+
+- PR \#935 review remediation: executable gate registry and fail-closed runtime context parsing ([pm-n41vay](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-n41vay.toon))
+- GH-926: warn before a stale pm binary mutates a project pinned to a newer CLI/SDK ([pm-1eted6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-1eted6.toon))
+- PR \#935 CI: preserve dependency-free fast-version startup and regenerate runtime contracts ([pm-dskxwf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dskxwf.toon))
+- Make stale-runtime compatibility classification action-aware across mixed CLI commands ([pm-zjelve](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-zjelve.toon))
+- CLI and SDK refusal contracts now preserve consistent codes and recovery semantics ([pm-0xmajx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0xmajx.toon))
+- Sentry exception capture never writes the pm.error_code and pm.exit_code tags the release gate reads, so every unexpected runtime error is unclassifiable by construction and blocks the daily cut for the full rolling window ([pm-qxo5iu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qxo5iu.toon))
+- Sentry PM-CLI-2S: resource-exhausted copy reports a high handled error without actionable storage guidance ([pm-4odf0c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-4odf0c.toon))
+- Sentry PM-CLI-2Q: expected snapshot-name validation is captured as a high production error ([pm-qyg51h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qyg51h.toon))
+- The release gate classifies production errors by message prose and reads none of the 236 error codes the product declares, so every waiver is a latent re-block and a broad substring is a silent waiver ([pm-dqtzva](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dqtzva.toon))
+- The mandatory command-wiring replication set is enforced only by a prose checklist, and the census shows partial application is the single largest recurring defect class in the record ([pm-7rrqsk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7rrqsk.toon))
+- pm get silently discards --output-include field names because entity reads bind the flag to sections while collection reads bind it to fields, and the omission receipt reports no omissions either way ([pm-0k19l7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0k19l7.toon))
+- GH-919: \_workspace author-attribution coordinates cannot be acknowledged ([pm-ety1qc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ety1qc.toon))
+- pm comments write response replays the entire accumulated history, so one append can emit hundreds of comments ([pm-9stazf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9stazf.toon))
+- GH-457: pm health hangs during vectorization check with no output (never-block violation) ([pm-tu71](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tu71.toon))
+
+### Security
+
+- GHSA-2v37-7h3g-55p8: pin patched nanoid in the Vite/PostCSS development graph ([pm-5dwz1a](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5dwz1a.toon))
+- GH-933: nested PM writes in non-PM linked tests can mutate the source project ([pm-alhqbz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-alhqbz.toon))
+
+### Other
+
+- One governed verification plan now drives local preflight and maps hosted release gates ([pm-ei6x66](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ei6x66.toon))
+- Every command declares its exit-code set, and the code distinguishes applied from applied-to-nothing ([pm-hqa8g1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-hqa8g1.toon))
+- Floor polarity for the tracker measurement ratchet, with graph edge and node floors declared ([pm-z0cfor](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-z0cfor.toon))
+- Refresh tsx to 4.23.11 with full release-gate proof ([pm-nw1y14](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-nw1y14.toon))
+
+## 2026.8.7 - 2026-08-07
+
+### Added
+
+- Caller-carried output sessions compose token budgets across reads and suppress repeated item facts ([pm-hid9g1](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-hid9g1.toon))
+- Fleet attribution analytics: per-harness and per-model throughput, rework, and defect-escape rates derived from immutable history alone ([pm-gw6uyq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-gw6uyq.toon))
+- Improvement ledger: measured properties of pm carry a recorded time series, because a ceiling proves a number did not grow and can never prove a change made it smaller ([pm-chahyq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-chahyq.toon))
+
+### Changed
+
+- Update @toon-format/toon to 4.1.1 and verify codec compatibility ([pm-ko35zx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-ko35zx.toon))
+
+### Fixed
+
+- Nested pm test coverage changes repository-root fixtures because outer PM_PATH sandboxing leaks into package-owned run-tests ([pm-ay3l0p](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ay3l0p.toon))
+- Read surfaces have no common row contract: field projection reaches 4 of 11 commands and the row collection sits under a different key on each, so no single shell or jq expression works across pm ([pm-sb0tns](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-sb0tns.toon))
+- Sentry PM-CLI-2W: rejected unknown-author acknowledgments are emitted as high production errors ([pm-c3uru0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-c3uru0.toon))
+- Expose live bounded provenance coverage over immutable history ([pm-1wiugq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-1wiugq.toon))
+- GH-915: Windows nightly Vite import portability and shared contract-fixture isolation regressions ([pm-ssd7vv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ssd7vv.toon))
+- GH-914: macOS extension source identity compares non-canonical /var and /private/var paths ([pm-eu46an](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-eu46an.toon))
+- The coverage gate every contributor is told to run is not a gate: run-tests.mjs coverage prints the shortfall and exits 0, so only CI can fail on coverage ([pm-2qqcgl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qqcgl.toon))
+- The one projection that promises completeness is the one that loses data: pm contracts --full drops all 76 structured command summaries, returns 160 bare name strings, and reports has_omissions false ([pm-x0iv17](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x0iv17.toon))
+- GH-910: keep extension assets outside item merge-driver patterns ([pm-t9qbmp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-t9qbmp.toon))
+- GH-911: preserve runtime dependency resolution in post-install activation probes ([pm-pg9599](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pg9599.toon))
+- GH-912 regression: restore atomic cross-owner seeded Plan creation ([pm-hxuqsa](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hxuqsa.toon))
+
+### Other
+
+- Refresh compatible tooling dependencies: tsx 4.23.8 and pm-changelog 2026.8.6 ([pm-l9fv1e](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-l9fv1e.toon))
+
 ## 2026.8.6 - 2026-08-06
 
 ### Fixed

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]="a16a4e5c-eaa5-59fd-a1ba-b5752e29ec47")}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]="52c705ab-a5c4-5b94-b806-4eaac31b6e9c")}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";
@@ -29,6 +29,7 @@ import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { runWithDiscoveredContextIntentContracts } from "../sdk/context-intent-runtime.js";
 import { 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";
 function resolvePmPackageRoot() {
     return resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
@@ -332,7 +333,7 @@ function buildPostActionTelemetryOutcome() {
     const processExitCode = typeof process.exitCode === "number" && Number.isFinite(process.exitCode) ? Math.max(0, Math.trunc(process.exitCode)) : undefined;
     const resultExitCode = readRecordNumber(result, "exit_code", "exitCode");
     const exitCode = processExitCode ?? resultExitCode ?? EXIT_CODE.SUCCESS;
-    const ok = exitCode === EXIT_CODE.SUCCESS;
+    const ok = isPmSuccessfulExitCode(exitCode);
     const errorCode = readRecordString(result, "error_code", "errorCode") ?? inferPostActionErrorCode(ok, exitCode);
     const errorCategory = normalizeTelemetryErrorCategory(readRecordString(result, "error_category", "errorCategory")) ??
         (!ok ? resolveTelemetryErrorCategory(errorCode) : undefined);
@@ -515,6 +516,7 @@ function extractCommandScopedOptions(command, commandArgs, extensionFlagDefiniti
     delete scoped.outputLimit;
     delete scoped.outputBudget;
     delete scoped.outputFormat;
+    delete scoped.outputSession;
     const looseOptions = parseLooseCommandOptions(commandArgs);
     for (const [key, value] of Object.entries(looseOptions)) {
         /* c8 ignore next */
@@ -1541,6 +1543,7 @@ function attachProgramLifecycleHooks(rootProgram) {
             outputLimit: rawGlobalOptions.outputLimit,
             outputBudget: rawGlobalOptions.outputBudget,
             outputFormat: rawGlobalOptions.outputFormat,
+            outputSession: rawGlobalOptions.outputSession,
         });
         await maybeRunFirstUseTelemetryPrompt(commandPath, globalOptions);
         const fallbackPmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
@@ -2451,4 +2454,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=a16a4e5c-eaa5-59fd-a1ba-b5752e29ec47
+//# debugId=52c705ab-a5c4-5b94-b806-4eaac31b6e9c

package/dist/cli/register-annotations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module cli/register-annotations
+ *
+ * Registers comment, note, and learning adapters around the shared bounded
+ * annotation SDK contract.
+ */
+import type { Command } from "commander";
+/** Converts a Commander token into a positive annotation index. */
+export type PositiveIntegerOptionParser = (value: string, previous: number | undefined) => number;
+/** Register bounded annotation commands on the root Commander program. */
+export declare function registerAnnotationCommands(program: Command, parsePositiveInteger: (flag: string) => PositiveIntegerOptionParser): void;

package/dist/cli/register-annotations.js

@@ -0,0 +1,195 @@
+
+!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]="0977d72e-6e4d-5ece-bfaf-eb24a4e9982c")}catch(e){}}();
+import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
+import { runComments } from "./commands/comments.js";
+import { runLearnings } from "./commands/learnings.js";
+import { runNotes } from "./commands/notes.js";
+import { addHiddenOption, getGlobalOptions, invalidateSearchCachesForMutation, printError, printResult, readOptionString, } from "./registration-helpers.js";
+function resolveCommentSources(text, options) {
+    const editIndex = typeof options.edit === "number" ? options.edit : undefined;
+    const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
+    const addFromOption = readOptionString(options, "add") ??
+        readOptionString(options, "body") ??
+        readOptionString(options, "comment");
+    const addFromPositional = typeof text === "string" ? text : undefined;
+    const readFromStdin = options.stdin === true;
+    const readFromFile = readOptionString(options, "file");
+    const sourceCount = Number(addFromOption !== undefined) +
+        Number(addFromPositional !== undefined) +
+        Number(readFromStdin) +
+        Number(readFromFile !== undefined);
+    if (sourceCount > 1) {
+        if (addFromOption !== undefined &&
+            addFromPositional !== undefined &&
+            !readFromStdin &&
+            readFromFile === undefined) {
+            throw new PmCliError("Specify comment text either as positional [text] or with --add, not both", EXIT_CODE.USAGE);
+        }
+        throw new PmCliError("Specify comment text with exactly one source: positional [text], --add, --stdin, or --file", EXIT_CODE.USAGE);
+    }
+    const add = addFromOption ?? addFromPositional;
+    return {
+        add,
+        readFromStdin,
+        readFromFile,
+        editIndex,
+        deleteIndex,
+        isMutation: typeof add === "string" ||
+            readFromStdin ||
+            readFromFile !== undefined ||
+            editIndex !== undefined ||
+            deleteIndex !== undefined,
+    };
+}
+function resolveSingleTextSource(label, positional, options) {
+    const addFromOption = readOptionString(options, "add");
+    const addFromPositional = typeof positional === "string" ? positional : undefined;
+    if (addFromOption !== undefined && addFromPositional !== undefined) {
+        throw new PmCliError(`Specify ${label} text either as positional [text] or with --add, not both`, EXIT_CODE.USAGE);
+    }
+    return addFromOption ?? addFromPositional;
+}
+async function runCommentsAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const sources = resolveCommentSources(text, options);
+    const result = await runComments(id, {
+        add: sources.add,
+        stdin: sources.readFromStdin,
+        file: sources.readFromFile,
+        edit: sources.editIndex,
+        delete: sources.deleteIndex,
+        limit: readOptionString(options, "limit"),
+        fullHistory: options.fullHistory === true,
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        ownershipAppendBypass: options.ownershipAppendBypass === true,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (sources.isMutation) {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printAnnotationResult("comments", result, globalOptions, startedAt);
+}
+async function runNotesAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const add = resolveSingleTextSource("note", text, options);
+    const result = await runNotes(id, {
+        add,
+        addJson: readOptionString(options, "addJson"),
+        stdin: options.stdin === true,
+        file: readOptionString(options, "file"),
+        edit: typeof options.edit === "number" ? options.edit : undefined,
+        delete: typeof options.delete === "number" ? options.delete : undefined,
+        limit: readOptionString(options, "limit"),
+        since: readOptionString(options, "since"),
+        eventType: readOptionString(options, "eventType"),
+        includeMeta: options.includeMeta === true,
+        fullHistory: options.fullHistory === true,
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        ownershipAppendBypass: options.ownershipAppendBypass === true,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (typeof add === "string" ||
+        typeof options.addJson === "string" ||
+        options.stdin === true ||
+        typeof options.file === "string" ||
+        typeof options.edit === "number" ||
+        typeof options.delete === "number") {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printAnnotationResult("notes", result, globalOptions, startedAt);
+}
+async function runLearningsAction(id, text, options, command) {
+    const globalOptions = getGlobalOptions(command);
+    const startedAt = Date.now();
+    const add = resolveSingleTextSource("learning", text, options);
+    const result = await runLearnings(id, {
+        add,
+        stdin: options.stdin === true,
+        file: readOptionString(options, "file"),
+        edit: typeof options.edit === "number" ? options.edit : undefined,
+        delete: typeof options.delete === "number" ? options.delete : undefined,
+        limit: readOptionString(options, "limit"),
+        fullHistory: options.fullHistory === true,
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+        ownershipAppendBypass: options.ownershipAppendBypass === true,
+        force: Boolean(options.force),
+    }, globalOptions);
+    if (typeof add === "string" ||
+        options.stdin === true ||
+        typeof options.file === "string" ||
+        typeof options.edit === "number" ||
+        typeof options.delete === "number") {
+        await invalidateSearchCachesForMutation(globalOptions, result);
+    }
+    printAnnotationResult("learnings", result, globalOptions, startedAt);
+}
+function printAnnotationResult(command, result, globalOptions, startedAt) {
+    printResult(result, globalOptions);
+    if (globalOptions.profile) {
+        printError(`profile:command=${command} took_ms=${Date.now() - startedAt}`);
+    }
+}
+/** Register bounded annotation commands on the root Commander program. */
+export function registerAnnotationCommands(program, parsePositiveInteger) {
+    const commentsCommand = program
+        .command("comments")
+        .argument("<id>", "Item id")
+        .argument("[text]", "Optional comment text shorthand (equivalent to --add)")
+        .option("--add <text>", "Add one comment entry (plain text fallback, text=<value>, markdown pairs, or - for stdin; CSV-like key fragments are preserved as plain text unless text is explicit)")
+        .option("--stdin", "Read comment text from stdin (supports multiline markdown)")
+        .option("--file <path>", "Read comment text from file (supports multiline markdown)")
+        .option("--edit <index>", "Replace the comment at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
+        .option("--delete <index>", "Delete the comment at 1-based <index>", parsePositiveInteger("--delete"))
+        .option("--limit <n>", "Return only latest n comments")
+        .option("--full-history", "Return the complete post-mutation comment history instead of a bounded receipt")
+        .option("--author [value]", "Comment author (optional; falls back to PM_AUTHOR/settings)")
+        .option("--message <value>", "History message")
+        .option("--force", "Force ownership override")
+        .description("List, add, edit, or delete comments for an item.")
+        .action(runCommentsAction);
+    addHiddenOption(commentsCommand, "--body <text>", "Alias for --add", false);
+    addHiddenOption(commentsCommand, "--comment <text>", "Alias for --add", false);
+    program
+        .command("notes")
+        .argument("<id>", "Item id")
+        .argument("[text]", "Optional note text shorthand (equivalent to --add; use - for stdin)")
+        .option("--add <text>", "Add a text note (- reads stdin)")
+        .option("--add-json <json>", "Append a merge-safe JSON event")
+        .option("--stdin", "Read note text from stdin")
+        .option("--file <path>", "Read note text from a UTF-8 file")
+        .option("--edit <index>", "Replace a 1-based note using the selected text input", parsePositiveInteger("--edit"))
+        .option("--delete <index>", "Delete the note at 1-based <index>", parsePositiveInteger("--delete"))
+        .option("--limit <n>", "Return only latest n notes")
+        .option("--since <timestamp>", "Filter JSON events from this ISO time")
+        .option("--event-type <value>", "Filter JSON events by top-level type")
+        .option("--include-meta", "Include count and truncation metadata")
+        .option("--full-history", "Return the complete post-mutation note history instead of a bounded receipt")
+        .option("--author [value]", "Author; defaults to PM_AUTHOR/settings")
+        .option("--message <value>", "History message")
+        .option("--force", "Force ownership override")
+        .description("Manage merge-safe text notes and JSON context events.")
+        .action(runNotesAction);
+    program
+        .command("learnings")
+        .argument("<id>", "Item id")
+        .argument("[text]", "Optional learning text shorthand (equivalent to --add; use - for stdin)")
+        .option("--add <text>", "Add one learning entry (plain text fallback, text=<value>, markdown pairs, or - for stdin; CSV-like key fragments are preserved as plain text unless text is explicit)")
+        .option("--stdin", "Read learning text from stdin (supports multiline markdown)")
+        .option("--file <path>", "Read learning text from file (supports multiline markdown)")
+        .option("--edit <index>", "Replace the learning at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
+        .option("--delete <index>", "Delete the learning at 1-based <index>", parsePositiveInteger("--delete"))
+        .option("--limit <n>", "Return only latest n learnings")
+        .option("--full-history", "Return the complete post-mutation learning history instead of a bounded receipt")
+        .option("--author [value]", "Learning author (optional; falls back to PM_AUTHOR/settings)")
+        .option("--message <value>", "History message")
+        .option("--force", "Force ownership override")
+        .description("List, add, edit, or delete learnings for an item.")
+        .action(runLearningsAction);
+}
+//# sourceMappingURL=register-annotations.js.map
+//# debugId=0977d72e-6e4d-5ece-bfaf-eb24a4e9982c

package/dist/cli/register-history-author.js

@@ -1,40 +1,17 @@
 
-!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]="d04ac41f-796d-5ccb-9e8e-cfa82c845f25")}catch(e){}}();
-import { EXIT_CODE, PmCliError, resolvePmRoot, } from "../sdk/runtime-primitives.js";
-import { acknowledgeUnknownAuthorHistoryEvents } from "../sdk/author-attribution.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]="50a7ce23-2abf-5240-b426-b73cb704e329")}catch(e){}}();
+import { resolvePmRoot } from "../sdk/runtime-primitives.js";
+import { acknowledgeUnknownAuthorHistoryEvents, resolveUnknownAuthorAcknowledgmentSelector, } from "../sdk/author-attribution.js";
 import { collect, getGlobalOptions, printResult, readOptionString, } from "./registration-helpers.js";
 async function runHistoryAuthorAcknowledgeAction(options, command) {
     const globalOptions = getGlobalOptions(command);
     const rawEvents = Array.isArray(options.event)
         ? options.event
         : [];
-    const allActionable = options.allActionable === true;
-    const hasExplicitEvents = rawEvents.length > 0;
-    if (hasExplicitEvents === allActionable) {
-        throw new PmCliError("Specify exactly one selector: repeat --event or pass --all-actionable.", EXIT_CODE.USAGE, {
-            code: "history_author_acknowledge_selector_required",
-            required: "Exactly one of --event or --all-actionable",
-            examples: [
-                'pm history-author-acknowledge --event pm-a1b2:4 --attributed-author agent --reviewer maintainer --reason "Verified provenance"',
-                'pm history-author-acknowledge --all-actionable --attributed-author import-agent --reviewer maintainer --reason "Reviewed the complete actionable set"',
-            ],
-        });
-    }
-    const events = rawEvents.map((value) => {
-        const separator = value.lastIndexOf(":");
-        const itemId = value.slice(0, separator).trim();
-        const line = Number(value.slice(separator + 1));
-        if (separator < 1 ||
-            !/^[a-z0-9][a-z0-9-]*$/iu.test(itemId) ||
-            !Number.isSafeInteger(line) ||
-            line < 1) {
-            throw new PmCliError(`history-author-acknowledge --event expects <item-id>:<one-based-line>, received "${value}".`, EXIT_CODE.USAGE);
-        }
-        return { item_id: itemId, line };
-    });
+    const selector = resolveUnknownAuthorAcknowledgmentSelector(rawEvents, options.allActionable === true);
     const result = await acknowledgeUnknownAuthorHistoryEvents(resolvePmRoot(process.cwd(), globalOptions.path), {
-        events,
-        all_actionable: allActionable,
+        events: selector.events,
+        all_actionable: selector.all_actionable,
         attributed_author: readOptionString(options, "attributedAuthor"),
         reviewer: readOptionString(options, "reviewer"),
         reason: readOptionString(options, "reason"),
@@ -54,4 +31,4 @@ export function registerHistoryAuthorAcknowledgeCommand(program) {
         .action(runHistoryAuthorAcknowledgeAction);
 }
 //# sourceMappingURL=register-history-author.js.map
-//# debugId=d04ac41f-796d-5ccb-9e8e-cfa82c845f25
+//# debugId=50a7ce23-2abf-5240-b426-b73cb704e329