@unbrained/pm-cli 2026.9.28 → 2026.9.30

package/docs/SDK_AUDITED_MUTATIONS.md

@@ -0,0 +1,52 @@
+# Audited SDK Settings and Item Updates
+
+The extension settings contract is tracked by
+[pm-wtqltn](../.agents/pm/issues/pm-wtqltn.toon). Full-item JSON annotation
+integrity is tracked by [pm-2589e6](../.agents/pm/issues/pm-2589e6.toon).
+
+## Extension settings
+
+An extension command receives a host-bound `sdk` in its `run` context. Use
+`sdk.mutateWorkspaceSettings` to change the current project's `settings.json`.
+The host chooses the tracker path and author, validates the complete result,
+serializes concurrent changes under the workspace lock, and records the change
+in workspace history. A copied extension needs no local SDK installation.
+
+```ts
+api.registerCommand({
+  name: "example hints",
+  flags: [{ long: "--operation-id", value_name: "id", value_type: "string" }],
+  run: ({ sdk, options }) =>
+    sdk.mutateWorkspaceSettings({
+      operationId: options.operationId,
+      mutate: (current) => ({
+        ...current,
+        ux: { ...current.ux, deprecation_hints: true },
+      }),
+    }),
+});
+```
+
+Supply a stable `operationId` for a logical operation within its registered
+command. The host scopes the ID to that command, so another command can use
+the same ID independently. Retrying an already recorded operation returns
+`replayed: true` without invoking `mutate`, writing settings, or appending
+another history event. `dryRun: true` calculates `changed` without changing settings or history;
+the same operation ID can then be used for the real mutation. A normal return
+also reports `changed` and `dry_run`. Invalid results fail before writing, and
+a history-append failure restores the previous settings bytes. The callback
+must derive its complete next settings object from the locked `current` value.
+The host applies the standard settings serializer, including legacy format
+coercion and collection-name sanitization, and runs active `onWrite` hooks
+after a changed write.
+
+## Full-item JSON updates
+
+`pm update <id> --stdin-json` accepts a full item read document. New comments,
+notes, and learnings in that document are appended through the normal item
+mutation. Persisted entries are an audit trail: changing or removing one in
+the submitted document now fails with
+`stdin_json_persisted_annotation_changed` before any item fields are written.
+This check also applies when the only submitted change is an annotation. Use
+`pm comments`, `pm notes`, or `pm learnings` with `--edit` to correct an
+existing entry; those commands write a history event for the correction.

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -103,12 +103,46 @@ Replacement requires at least one corresponding `--file` or `--doc` value and ca
 
 Repeating an already-present `pm files --add` or `pm docs --add` batch is a true no-op: `changed` is false, the item file is not rewritten, and append-only history receives no synthetic mutation entry.
 
+An explicit non-empty replacement note updates the existing path/scope entry
+atomically. A bare-path retry preserves its note; a different scope identifies
+a separate link. The same rule applies to glob additions and standalone
+`--note`. Migration collisions first retain the established last matching
+entry; an explicit note revision then applies to that surviving identity.
+This fixes [pm-zqxlfs](../.agents/pm/issues/pm-zqxlfs.toon):
+
+```bash
+pm files <id> --add path=src/new.ts,note="verified current implementation"
+pm docs <id> --add docs/new.md --note "verified current contract"
+```
+
 Audited history redaction participates in the same projection transaction as
 ordinary item mutation. After rewriting an item and its history stream, pm
 invalidates drift verification state and incrementally refreshes the metadata
 index before releasing the derived-index lock. A warmed index therefore cannot
 pair pre-redaction item content with post-redaction history during validation.
 
+## Compact Plan mutation receipts
+
+Tracked by [pm-hqy7lr](../.agents/pm/issues/pm-hqy7lr.toon).
+CLI and MCP Plan mutations return identity, action, step identity when available,
+complete step counts, materialization/skip/warning counts, and an inspection
+command. They omit bodies, resume context, and unrelated steps, so a single-step
+update does not grow with the Plan. `pm plan show <id> --depth deep` retrieves
+the complete current Plan without repeating a mutation. The omission receipt
+explicitly distinguishes this acknowledgement from a full read.
+Local CLI/SDK recovery commands include the resolved `--pm-path`, safely quoted,
+so they inspect the same tracker even with a non-default root. MCP receipts
+omit the server-resolved filesystem root in both compact and full output.
+For MCP recovery, call `pm_plan` with `subcommand: "show"`, `depth: "deep"`,
+the receipt ID, and the original request's workspace selection (`path` or `cwd`).
+
+SDK `runPlan` retains its full typed result and adds `mutation_receipt` for
+consumers that need a compact acknowledgement. Existing full transport output
+is available with CLI `--full-changed-fields` or MCP `fullChangedFields: true`.
+The named `PlanMutationReceipt` type is exported from `@unbrained/pm-cli/sdk`.
+CLI `--no-changed-fields` also selects a compact Plan receipt.
+Read-only `plan show` retains its existing projection behavior.
+
 ## Operational receipts
 
 Linked tests recognize compound acquisition failures such as “could not acquire … lock” together with contention context such as “already running” or “held by another” as `infra_collision`. Generic assertion text mentioning a lock or timeout remains `assertion_failure`, preventing false infrastructure classifications. A command refused by clone-local provenance policy is classified separately as `trust_refusal`, so reports do not misstate a pre-execution safety decision as an assertion failure.

package/docs/agent-task-token-baseline.json

@@ -1,7 +1,7 @@
 {
   "version": 4,
   "transcript_version": 2,
-  "transcript_digest": "sha256:b8a6aea318c41e6a40dbcaf8094da8397ca747515a7df249d35c1f21ad94a307",
+  "transcript_digest": "sha256:6d4041acfaa4075dde1972d6127a74f18916f7661738b4f5d5fd47a61c179a78",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
@@ -259,7 +259,33 @@
           "accounting_mode": "self_reported"
         }
       ]
+    },
+    {
+      "id": "plan-execution-mutations",
+      "max_estimated_tokens": 848,
+      "steps": [
+        {
+          "id": "create-plan",
+          "max_estimated_tokens": 21,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "add-step",
+          "max_estimated_tokens": 275,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "complete-step",
+          "max_estimated_tokens": 274,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect-plan",
+          "max_estimated_tokens": 278,
+          "accounting_mode": "self_reported"
+        }
+      ]
     }
   ],
-  "composite_max_estimated_tokens": 13034
+  "composite_max_estimated_tokens": 13882
 }

package/docs/agent-task-transcripts.json

@@ -17,13 +17,22 @@
         ],
         "capability_evidence": {
           "workspace_state": [
-            { "step_id": "context", "field_path": "summary.active_items" }
+            {
+              "step_id": "context",
+              "field_path": "summary.active_items"
+            }
           ],
           "active_ownership": [
-            { "step_id": "context", "field_path": "activity" }
+            {
+              "step_id": "context",
+              "field_path": "activity"
+            }
           ],
           "actionable_work": [
-            { "step_id": "context", "field_path": "hierarchy" }
+            {
+              "step_id": "context",
+              "field_path": "hierarchy"
+            }
           ]
         }
       },
@@ -36,13 +45,22 @@
         ],
         "capability_evidence": {
           "workspace_state": [
-            { "step_id": "next", "field_path": "summary.in_progress" }
+            {
+              "step_id": "next",
+              "field_path": "summary.in_progress"
+            }
           ],
           "active_ownership": [
-            { "step_id": "next", "field_path": "held_by_others" }
+            {
+              "step_id": "next",
+              "field_path": "held_by_others"
+            }
           ],
           "actionable_work": [
-            { "step_id": "next", "field_path": "recommended.id" }
+            {
+              "step_id": "next",
+              "field_path": "recommended.id"
+            }
           ]
         }
       },
@@ -55,12 +73,23 @@
         ],
         "capability_evidence": {
           "workspace_state": [
-            { "step_id": "context", "field_path": "summary.active_items" }
+            {
+              "step_id": "context",
+              "field_path": "summary.active_items"
+            }
           ],
           "active_ownership": [
-            { "step_id": "in-progress", "field_path": "items" }
+            {
+              "step_id": "in-progress",
+              "field_path": "items"
+            }
           ],
-          "actionable_work": [{ "step_id": "open", "field_path": "items" }]
+          "actionable_work": [
+            {
+              "step_id": "open",
+              "field_path": "items"
+            }
+          ]
         }
       }
     ]
@@ -186,7 +215,9 @@
           "expected_accounting_mode": "self_reported",
           "required_fields": ["code", "refusal", "recovery"],
           "expected_error_code": "unknown_context_intent",
-          "expected_field_values": { "recovery.recovery_mode": "compact" },
+          "expected_field_values": {
+            "recovery.recovery_mode": "compact"
+          },
           "expected_refusal_surface": "--for"
         },
         {
@@ -266,7 +297,9 @@
           "expected_output_kind": "entity",
           "expected_accounting_mode": "self_reported",
           "required_fields": ["item.id", "item.status"],
-          "expected_field_values": { "item.status": "open" }
+          "expected_field_values": {
+            "item.status": "open"
+          }
         },
         {
           "id": "close",
@@ -283,7 +316,9 @@
           "expected_output_kind": "entity",
           "expected_accounting_mode": "self_reported",
           "required_fields": ["item.id", "item.status"],
-          "expected_field_values": { "item.status": "closed" }
+          "expected_field_values": {
+            "item.status": "closed"
+          }
         }
       ]
     },
@@ -329,7 +364,9 @@
           "expected_output_kind": "collection",
           "expected_accounting_mode": "self_reported",
           "required_fields": ["rows", "outcome", "exit_code"],
-          "expected_field_values": { "outcome": "partial_effect" }
+          "expected_field_values": {
+            "outcome": "partial_effect"
+          }
         },
         {
           "id": "no-effect",
@@ -347,7 +384,93 @@
           "expected_output_kind": "collection",
           "expected_accounting_mode": "self_reported",
           "required_fields": ["rows", "outcome", "exit_code"],
-          "expected_field_values": { "outcome": "no_effect" }
+          "expected_field_values": {
+            "outcome": "no_effect"
+          }
+        }
+      ]
+    },
+    {
+      "id": "plan-execution-mutations",
+      "description": "Create a Plan, add and complete a step, then inspect its durable evidence without echoing the full Plan on each mutation.",
+      "steps": [
+        {
+          "id": "create-plan",
+          "args": [
+            "create",
+            "--id",
+            "pm-transcript-plan",
+            "--type",
+            "Plan",
+            "--title",
+            "Transcript execution Plan",
+            "--create-mode",
+            "progressive"
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "status"]
+        },
+        {
+          "id": "add-step",
+          "args": [
+            "plan",
+            "add-step",
+            "pm-transcript-plan",
+            "--step-title",
+            "Verify result",
+            "--step-body",
+            "Durable execution context retained for later inspection."
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "diagnostic",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": [
+            "id",
+            "step.id",
+            "steps_summary.total",
+            "inspection_command"
+          ],
+          "expected_field_values": {
+            "kind": "plan_mutation",
+            "steps_summary.total": 1
+          }
+        },
+        {
+          "id": "complete-step",
+          "args": [
+            "plan",
+            "complete-step",
+            "pm-transcript-plan",
+            "plan-step-001",
+            "--step-evidence",
+            "Verified result"
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "diagnostic",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": [
+            "id",
+            "step.status",
+            "steps_summary.completed",
+            "omission_receipt"
+          ],
+          "expected_field_values": {
+            "step.status": "completed",
+            "steps_summary.completed": 1
+          }
+        },
+        {
+          "id": "inspect-plan",
+          "args": ["plan", "show", "pm-transcript-plan", "--depth", "deep"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "diagnostic",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["plan.steps", "plan.steps_summary.completed"],
+          "expected_field_values": {
+            "plan.steps_summary.completed": 1
+          }
         }
       ]
     }