@unbrained/pm-cli 2026.8.27 → 2026.8.29

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

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 2026.8.29 - 2026-08-29
+
+### Fixed
+
+- GH-1144: hash-only merge receipts contradict report output and cannot reconcile truthfully ([pm-z1z96w](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-z1z96w.toon))
+- GH-1146/1147: external blockers remain stale and validation recommends deleting them ([pm-yhle2e](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-yhle2e.toon))
+- GH-1140: reject ambiguous bare comma tuples for linked file and test mutations ([pm-nc94mk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-nc94mk.toon))
+- GH-1148: cached drift mismatch can falsely report tracker corruption ([pm-sxg7wl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-sxg7wl.toon))
+- GH-1138: linked test name filters can pass after executing zero tests ([pm-ntnv4k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ntnv4k.toon))
+- GH-1136: npm 12 object-form npm pack receipts break registry package installs ([pm-xrjy8o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xrjy8o.toon))
+- GH-1135: item_hash_version 2 still masks writer hash divergence as corruption ([pm-2qahia](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qahia.toon))
+- The annotation key=value grammar has three divergent comma behaviours, two of which silently corrupt the evidence text before it is made immutable ([pm-hu92i3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hu92i3.toon))
+- GH-1150: health remediation for pending merge receipts must perform the repair ([pm-r0p3at](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-r0p3at.toon))
+- GH-1134: required collection recovery omits truthful --clear-\* intent ([pm-t7wl00](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-t7wl00.toon))
+- GH-1143: Claude session-file provenance resolver ignores real nested stream fields ([pm-f60039](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-f60039.toon))
+- GH-1137: linked docs writes silently persist nonexistent workspace paths ([pm-hiqlkh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hiqlkh.toon))
+- Sentry release gate aborts valid API queries at a fixed 15-second deadline ([pm-b9g2cs](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-b9g2cs.toon))
+
+### Other
+
+- Refresh @sentry/node 10.72 with packed SDK and release proof ([pm-mwhv33](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-mwhv33.toon))
+- Refresh compatible 2026-08-29 dependency releases ([pm-vwuidf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-vwuidf.toon))
+- Close the jscpd/CodeFactor sensitivity gap: minTokens 115 misses low-token table clones the CodeFactor bot still files ([pm-xspd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-xspd.toon))
+
+## 2026.8.28 - 2026-08-28
+
+### Fixed
+
+- Repository test runner inherits production Sentry and turns negative CLI fixtures into release-blocking incidents ([pm-5ug5xq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5ug5xq.toon))
+- Broad squash commits overflow hosted-analysis tree lookup and falsely lose reviewed PR provenance ([pm-gactwj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gactwj.toon))
+- Golden agent-transcript replay: measure tokens-per-completed-task as a CI-visible DX regression gate ([pm-8pnj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-8pnj.toon))
+- Unknown-option refusal textual flags bypass structured global-option filtering ([pm-x4wbui](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x4wbui.toon))
+- Agent-task transcript recovery accepts a refusal as a successful retry ([pm-o360q6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o360q6.toon))
+- Close lifecycle bypasses reproducible process clock ([pm-hmpu4p](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hmpu4p.toon))
+- GH-1132: opt-in idempotent annotation append (ifAbsent/--if-absent) prevents retry-driven context duplication; duplicate appends remain available by default ([pm-ea1yh2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ea1yh2.toon))
+- Agent-task transcripts accept declared no-effect and partial-effect successful exits ([pm-wanwyc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wanwyc.toon))
+- Agent-task baselines accept missing task and composite token ceilings ([pm-aksavu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-aksavu.toon))
+- Agent-task closeout claims lack linked full-verification commands ([pm-ervmsc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ervmsc.toon))
+- CLI transport-floor RSS admission false-fails on single-sample page noise ([pm-pz49xc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pz49xc.toon))
+- Unknown-option refusals identify the actual rejected flag and fail closed at delimiters ([pm-fo8g7j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fo8g7j.toon))
+- Agent-task gate accepts incidental substrings as required-field completeness ([pm-o7u08u](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o7u08u.toon))
+- Completed-task transcripts require terminal success, exclusive refusal metadata, and complete recovery ([pm-wa39rl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wa39rl.toon))
+- Agent-task token replay trusts missing or incorrect accounting estimates ([pm-ok2kdn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ok2kdn.toon))
+
+### Security
+
+- GH-1131: macOS Node 24 nightly cannot create the Skills-over-MCP special-file socket fixture ([pm-k23c4c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-k23c4c.toon))
+
 ## 2026.8.27 - 2026-08-27
 
 ### Added
@@ -887,10 +935,10 @@
 
 ### Other
 
+- CLI transport overhead budget: gate the per-invocation bootstrap floor and the CLI-vs-SDK delta, not just absolute scale numbers ([pm-yse5dt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yse5dt.toon))
 - CI/CD + test-suite performance: in-process CLI runner and dedupe redundant matrix legs ([pm-7rlp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-7rlp.toon))
 - ADR: agent identity model — stable author namespace plus structured harness, model, and session provenance ([pm-qwuber](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-qwuber.toon))
 - Public SDK surface shape: 881 exports behind one flat entrypoint with no capability tiering and a 250ms eager import cost ([pm-38bskj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-38bskj.toon))
-- CLI transport overhead budget: gate the per-invocation bootstrap floor and the CLI-vs-SDK delta, not just absolute scale numbers ([pm-yse5dt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yse5dt.toon))
 
 ## 2026.7.25 - 2026-07-25
 

package/dist/cli/error-guidance.js

@@ -1,9 +1,10 @@
 
-!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]="bb31fb1f-bf61-5eab-aa63-5d04fbac282f")}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]="ca79853d-468c-5522-b5f9-6509c66e3d9b")}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";
+import { stripGlobalBootstrapTokens } from "../sdk/cli-bootstrap.js";
 /** Compact an error envelope to fields that change the caller's next action. */
 export function projectLeanErrorEnvelope(envelope) {
     const { why: _why, title: _title, ...actionable } = envelope;
@@ -307,15 +308,36 @@ function attachStructuredGuidanceDetails(payload, message) {
 function resolveRefusalCandidateFlag(message, normalizedArgs) {
     if (message.flag)
         return message.flag;
-    return message.recovery?.provided_fields?.find((field) => field !== "--json" &&
-        field !== "--quiet" &&
-        normalizedArgs.includes(field));
+    const isAdmissibleCandidate = (flag) => {
+        const canonicalFlag = flag.split("=", 1)[0];
+        return (stripGlobalBootstrapTokens([canonicalFlag]).length > 0 &&
+            !["--help", "--no-changed-fields", "--version"].includes(canonicalFlag) &&
+            normalizedArgs.some((argument) => argument === canonicalFlag ||
+                argument.startsWith(`${canonicalFlag}=`)));
+    };
+    const mentionedFlag = [
+        ...`${message.title} ${message.happened}`.matchAll(/--[A-Za-z0-9][A-Za-z0-9_-]*/gu),
+    ]
+        .map((match) => match[0])
+        .find((flag) => isAdmissibleCandidate(flag));
+    if (mentionedFlag)
+        return mentionedFlag;
+    return message.recovery?.provided_fields
+        ?.map((field) => field.split("=", 1)[0])
+        .find((field) => isAdmissibleCandidate(field));
 }
 function resolveRefusalRejectedValue(message, normalizedArgs, candidateFlag) {
     if (message.value !== undefined)
         return message.value;
     if (candidateFlag) {
-        return normalizedArgs[normalizedArgs.indexOf(candidateFlag) + 1];
+        const candidateArgument = normalizedArgs.find((argument) => argument === candidateFlag || argument.startsWith(`${candidateFlag}=`));
+        if (candidateArgument?.startsWith(`${candidateFlag}=`)) {
+            return candidateArgument.slice(candidateFlag.length + 1);
+        }
+        const candidateIndex = normalizedArgs.indexOf(candidateFlag);
+        return candidateIndex >= 0
+            ? normalizedArgs[candidateIndex + 1]
+            : undefined;
     }
     const allowedValues = message.recovery?.allowed_values;
     if (!allowedValues?.length)
@@ -941,6 +963,34 @@ function buildUnknownOptionNextSteps(optionName, commandName, suggestions, candi
             : undefined,
     ].filter((entry) => typeof entry === "string");
 }
+/**
+ * Publish a shell-free correction only when removing the unknown token leaves
+ * positional ownership unambiguous; explicit producer guidance stays authoritative.
+ */
+function resolveUnknownOptionRetry(context, optionName) {
+    if (context.suggestedRetryCommand !== undefined) {
+        return { retryCommand: context.suggestedRetryCommand };
+    }
+    const normalizedArgs = context.normalizedInvocationArgs;
+    if (normalizedArgs === undefined)
+        return {};
+    if (normalizedArgs.filter((argument) => argument === optionName || argument.startsWith(`${optionName}=`)).length !== 1) {
+        return {};
+    }
+    const optionIndex = normalizedArgs.findIndex((argument) => argument === optionName || argument.startsWith(`${optionName}=`));
+    if (optionIndex < 0 ||
+        normalizedArgs.includes("--") ||
+        (!normalizedArgs[optionIndex]?.includes("=") &&
+            optionIndex !== normalizedArgs.length - 1 &&
+            normalizedArgs[optionIndex + 1]?.startsWith("-") !== true)) {
+        return {};
+    }
+    const suggestedRetryArgs = stripGlobalBootstrapTokens(normalizedArgs.filter((_, index) => index !== optionIndex));
+    return {
+        retryCommand: renderPmCommand(suggestedRetryArgs),
+        suggestedRetryArgs,
+    };
+}
 function buildUnknownOptionGuidance(message, commandName, context) {
     const unknownOption = message.match(/unknown option '([^']+)'/);
     if (!unknownOption) {
@@ -949,7 +999,7 @@ function buildUnknownOptionGuidance(message, commandName, context) {
     const guidanceContext = context ?? {};
     const optionName = unknownOption[1];
     const suggestions = normalizeOptionFlags(guidanceContext.unknownOptionSuggestions) ?? [];
-    const retryCommand = guidanceContext.suggestedRetryCommand;
+    const { retryCommand, suggestedRetryArgs } = resolveUnknownOptionRetry(guidanceContext, optionName);
     if (commandName === "update" &&
         (optionName === "--file" || optionName === "--doc")) {
         return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
@@ -966,10 +1016,14 @@ function buildUnknownOptionGuidance(message, commandName, context) {
         happened: `Commander does not recognize option ${optionName} for this command path.`,
         required: UNKNOWN_OPTION_REQUIRED_BY_SCOPE[candidateContext.optionScope],
         why: "Option contracts are command-specific and intentionally validated.",
+        flag: optionName,
+        value: optionName,
         examples,
         nextSteps,
         recovery: buildCommanderRecoveryPayload(context, {
             suggested_flags: suggestions.length > 0 ? suggestions : undefined,
+            suggested_retry: retryCommand,
+            suggested_retry_args: suggestedRetryArgs,
             candidate_commands: candidateContext.otherCommands,
             candidate_commands_total: candidateContext.candidateTotal || undefined,
             candidate_commands_truncated: guidanceContext.unknownOptionOtherCommandsTruncated,
@@ -1297,4 +1351,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=bb31fb1f-bf61-5eab-aa63-5d04fbac282f
+//# debugId=ca79853d-468c-5522-b5f9-6509c66e3d9b

package/dist/cli/register-annotations.js

@@ -1,5 +1,5 @@
 
-!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]="263a15b4-5537-5e11-b0c0-3da453ee0357")}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]="775518a4-ff3e-5a54-8fbd-b2c4863e23db")}catch(e){}}();
 import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
 import { renderPmCommand } from "../sdk/command-line.js";
 import { runComments } from "./commands/comments.js";
@@ -93,13 +93,33 @@ function resolveCommentSources(text, options) {
             deleteIndex !== undefined,
     };
 }
-function resolveSingleTextSource(label, positional, options) {
+/** Resolves every mutation-bearing source for notes and learnings once. */
+function resolveSingleAnnotationSources(label, positional, options) {
     const addFromOption = resolveAnnotationTextAliases(label, options, label === "note" ? ["add", "text", "note"] : ["add", "text"]);
     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;
+    const add = addFromOption ?? addFromPositional;
+    const addJson = label === "note" ? readOptionString(options, "addJson") : undefined;
+    const readFromStdin = options.stdin === true;
+    const readFromFile = readOptionString(options, "file");
+    const editIndex = typeof options.edit === "number" ? options.edit : undefined;
+    const deleteIndex = typeof options.delete === "number" ? options.delete : undefined;
+    return {
+        add,
+        addJson,
+        readFromStdin,
+        readFromFile,
+        editIndex,
+        deleteIndex,
+        isMutation: typeof add === "string" ||
+            addJson !== undefined ||
+            readFromStdin ||
+            readFromFile !== undefined ||
+            editIndex !== undefined ||
+            deleteIndex !== undefined,
+    };
 }
 async function runCommentsAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
@@ -114,12 +134,13 @@ async function runCommentsAction(id, text, options, command) {
         delete: sources.deleteIndex,
         limit: readOptionString(options, "limit"),
         fullHistory: options.fullHistory === true,
+        ifAbsent: options.ifAbsent === true,
         author: readOptionString(options, "author"),
         message: readOptionString(options, "message"),
         ownershipAppendBypass: options.ownershipAppendBypass === true,
         force: Boolean(options.force),
     }, globalOptions);
-    if (sources.isMutation) {
+    if (sources.isMutation && result.changed !== false) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printAnnotationResult("comments", result, globalOptions, startedAt);
@@ -128,30 +149,26 @@ async function runNotesAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
     assertNoTransposedAnnotationAction("notes", id, text, options);
-    const add = resolveSingleTextSource("note", text, options);
+    const sources = resolveSingleAnnotationSources("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,
+        add: sources.add,
+        addJson: sources.addJson,
+        stdin: sources.readFromStdin,
+        file: sources.readFromFile,
+        edit: sources.editIndex,
+        delete: sources.deleteIndex,
         limit: readOptionString(options, "limit"),
         since: readOptionString(options, "since"),
         eventType: readOptionString(options, "eventType"),
         includeMeta: options.includeMeta === true,
         fullHistory: options.fullHistory === true,
+        ifAbsent: options.ifAbsent === 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") {
+    if (sources.isMutation && result.changed !== false) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printAnnotationResult("notes", result, globalOptions, startedAt);
@@ -160,25 +177,22 @@ async function runLearningsAction(id, text, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
     assertNoTransposedAnnotationAction("learnings", id, text, options);
-    const add = resolveSingleTextSource("learning", text, options);
+    const sources = resolveSingleAnnotationSources("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,
+        add: sources.add,
+        stdin: sources.readFromStdin,
+        file: sources.readFromFile,
+        edit: sources.editIndex,
+        delete: sources.deleteIndex,
         limit: readOptionString(options, "limit"),
         fullHistory: options.fullHistory === true,
+        ifAbsent: options.ifAbsent === 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") {
+    if (sources.isMutation && result.changed !== false) {
         await invalidateSearchCachesForMutation(globalOptions, result);
     }
     printAnnotationResult("learnings", result, globalOptions, startedAt);
@@ -195,14 +209,15 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .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("--add <text>", "Append comment text; use text=<value> for structured input or - for stdin")
         .option("--stdin", "Read comment text from stdin (supports multiline markdown)")
         .option("--file <path>", "Read comment text from a file or stdin (-)")
-        .option("--edit <index>", "Replace the comment at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
+        .option("--edit <index>", "Replace one comment using 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("--full-history", "Return complete comment history instead of a bounded mutation receipt")
+        .option("--if-absent", "Append only when resolved author and text are absent")
+        .option("--author [value]", "Comment author; defaults to PM_AUTHOR or settings")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
         .description("List, add, edit, or delete comments for an item.")
@@ -213,10 +228,10 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
     const notesCommand = program
         .command("notes")
         .argument("<id>", "Item id")
-        .argument("[text]", "Optional note text shorthand (equivalent to --add; use - for stdin)")
+        .argument("[text]", "Optional note text shorthand for --add")
         .option("--add <text>", "Add a text note (- reads stdin)")
         .option("--note <text>", "Alias for --add")
-        .option("--add-json <json>", "Append a merge-safe JSON event")
+        .option("--add-json <json>", "Append a JSON event")
         .option("--stdin", "Read note text from stdin")
         .option("--file <path>", "Read note from file or stdin (-)")
         .option("--edit <index>", "Replace a 1-based note using the selected text input", parsePositiveInteger("--edit"))
@@ -225,7 +240,8 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .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("--full-history", "Return complete note history instead of a bounded receipt")
+        .option("--if-absent", "Append only when resolved author and text are absent")
         .option("--author [value]", "Author; defaults to PM_AUTHOR/settings")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
@@ -235,14 +251,15 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
     const learningsCommand = 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)")
+        .argument("[text]", "Optional learning text shorthand for --add")
+        .option("--add <text>", "Append learning text; use text=<value> or - for stdin")
+        .option("--stdin", "Read learning text from stdin")
         .option("--file <path>", "Read learning text from a file or stdin (-)")
-        .option("--edit <index>", "Replace the learning at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
+        .option("--edit <index>", "Replace one learning using 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("--full-history", "Return complete learning history instead of a bounded receipt")
+        .option("--if-absent", "Append only when resolved author and text are absent")
         .option("--author [value]", "Learning author (optional; falls back to PM_AUTHOR/settings)")
         .option("--message <value>", "History message")
         .option("--force", "Force ownership override")
@@ -251,4 +268,4 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
     addHiddenOption(learningsCommand, "--text <text>", "Alias for --add", false);
 }
 //# sourceMappingURL=register-annotations.js.map
-//# debugId=263a15b4-5537-5e11-b0c0-3da453ee0357
+//# debugId=775518a4-ff3e-5a54-8fbd-b2c4863e23db