@unbrained/pm-cli 2026.9.18 → 2026.9.19

package/docs/MCP_OPTION_CONFORMANCE.md

@@ -0,0 +1,41 @@
+# MCP Option Conformance
+
+Tracked by [pm-v0s2rm](../.agents/pm/chores/pm-v0s2rm.toon).
+
+An integration test can pass while an undeclared option is ignored. That leaves
+the test asserting a behavior it never exercised. The repository therefore
+treats emitted MCP unknown-option diagnostics as test failures, while the
+production server retains its advisory warning behavior for clients.
+
+Every run using [vitest.config.ts](../vitest.config.ts) installs
+[McpContractReporter](../scripts/mcp-contract-reporter.mts). The reporter records
+the emitting file, full test name, option, tool, and action, and rejects the run
+after execution even when all assertions pass. Unattributed warnings also fail.
+Diagnostics retain option names, never option values.
+
+The sandboxed test runner also retains the reporter when command-line reporter
+selection overrides the config, including CI coverage shards that emit blobs.
+
+Intentional negative tests must have an exact entry in
+`MCP_OPTION_WARNING_ALLOWLIST`, including a reason. A matching file or test alone
+does not exempt other warning identities. The current exemption verifies that
+mutation-shaped options cannot mutate a read tool. New integration behavior
+should use declared parameters and assert the actual resulting state.
+
+The [gate registry](../scripts/release/gate-registry.json) registers this check
+as `mcp-option-contracts`. Its
+[negative control](../tests/unit/scripts/mcp-contract-reporter.spec.ts) starts a
+real Vitest child process whose assertion passes but whose undeclared-option
+diagnostic must produce exit status 1. Run the gate and its integration consumers
+with the sandboxed repository runner:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/scripts/mcp-contract-reporter.spec.ts tests/integration/mcp-dynamic-package-actions.spec.ts tests/unit/mcp/mcp-server-nested-options.spec.ts
+```
+
+Published MCP acceptance also isolates project and global configuration, tracked
+by [pm-prmt1y](../.agents/pm/issues/pm-prmt1y.toon). The npm, npx, and bunx checks
+use temporary tracker roots for both stdio and HTTP servers. This prevents a
+caller's installed skills from changing discovery pagination and hiding the
+bundled skills being verified. Protocol and skill-content assertions remain
+mandatory; acceptance processes disable production telemetry and Sentry.

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -19,7 +19,11 @@ and canonical TOON tables are tracked by
 is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon) and
 [pm-oahhyc](../.agents/pm/issues/pm-oahhyc.toon). Exact command-local
 projection discovery is tracked by
-[pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon).
+[pm-q4isdq](../.agents/pm/issues/pm-q4isdq.toon). Shared graph defaults and
+scale enforcement are tracked by [pm-mfy1ux](../.agents/pm/issues/pm-mfy1ux.toon).
+
+For enforcement of declared MCP input options in repository tests, see
+[MCP Option Conformance](MCP_OPTION_CONFORMANCE.md).
 
 ## Agent Quick Context
 
@@ -167,7 +171,19 @@ Passing `--full` with the corresponding compact flag is a usage error. An
 explicit full request and the default full request produce the same payload
 shape; the flag exists as a machine-actionable restore instruction.
 
-`graph impact` is bounded to ten rows by default, returns `next_cursor` when
+Graph row collections default to ten rows, including hierarchy and ordering
+traversals, audit findings, and slack's critical path. The public
+`GRAPH_QUERY_DEFAULTS` contract is available from `@unbrained/pm-cli/sdk/graph`
+and `@unbrained/pm-cli/sdk/contracts`; `pm contracts --command graph --flags-only`
+declares the same defaults before invoking a graph query. Analytics still compute over the complete graph. `--full`
+restores row collections, while `--limit` chooses a finite cap; combining those
+two controls is rejected. Path enumeration retains its separate five-path,
+eight-edge-depth and 10,000-expansion safety defaults. Audit evidence uses
+`--sample` independently of the finding-row limit. The thousand-item graph
+regression enumerates every registered subcommand, bounds serialized output,
+and proves full traversal and cursor continuation.
+
+`graph impact` returns `next_cursor` when
 more affected nodes exist, and accepts `--after <cursor>` to resume in stable
 breadth-first order. `graph impact --full` is the explicit unbounded override;
 combining `--full` with `--limit` is rejected. A zero-row page remains

package/docs/PERFORMANCE.md

@@ -135,3 +135,40 @@ Review the report and budget diff together. Before a refresh, compare the delive
 ## Startup and observability
 
 Sentry is loaded only when an error-reporting path actually initializes it. Disabled and normal successful commands do not resolve or compile the `@sentry/node` → OpenTelemetry → Undici graph. The loader uses the package's supported CommonJS export after the opt-out gate, preserving the repo-wide ban on dynamic/inline imports while keeping enabled capture, sanitization, and flush behavior intact.
+
+## Invocation timing
+
+Tracked by [pm-ag9nka](../.agents/pm/issues/pm-ag9nka.toon).
+
+Use `pm --profile list --limit 5` to print diagnostics on stderr while retaining
+normal stdout (including JSON). Every executable invocation with `--profile`
+emits one final receipt on normal process drain, including help, version, and
+handled refusals:
+
+```text
+profile:command=list took_ms=20
+profile:invocation total_ms=324.125 scope=process_start_to_output_drain command_took_ms_scope=handler
+```
+
+`total_ms` uses monotonic runtime uptime, starting before module initialization
+and ending after pending command output and event-loop work drain. It includes
+bootstrap, settings/schema and extension loading, dispatch, rendering, and
+foreground cleanup. Existing `profile:command` records retain their compatible
+`took_ms` field; `command_took_ms_scope=handler` explicitly labels those narrower
+spans. Extension discovery timing is another component, never an invocation
+total. Components may overlap and must not be added to the total.
+
+The total excludes parent-side scheduling/spawn, final OS teardown, and remote
+telemetry delivery after a detached flush. A forcibly terminated process may
+never reach the drain callback. In-process SDK calls do not emit a process-total
+receipt: their host owns the lifetime. `--profile` after the `--` positional
+terminator does not enable the receipt.
+
+The real-process regression compares the reported total against external wall
+time across query, mutation, configuration, schema, health, discovery, and
+refusal paths. It permits parent/teardown overhead of the greater of 250 ms or
+25% of external wall time, and no more than 5 ms of clock rounding above it.
+This is an instrument agreement tolerance, not a performance budget. Existing
+transport/scale gates retain external end-to-end process wall time and their
+unchanged stricter regression budgets; never gate invocation latency on handler
+`took_ms`.

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -7,7 +7,8 @@ Tracker references: [pm-9wbiye](../.agents/pm/issues/pm-9wbiye.toon),
 [pm-eq9dlw](../.agents/pm/issues/pm-eq9dlw.toon), and
 [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), plus
 [pm-5q8wa0](../.agents/pm/issues/pm-5q8wa0.toon) and
-[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon).
+[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon) and
+[pm-4f1l7f](../.agents/pm/issues/pm-4f1l7f.toon).
 
 Project management is context management. The public SDK therefore carries a
 session's purpose and episode boundary through the same immutable history that
@@ -129,8 +130,8 @@ public SDK exports for custom hosts.
 the bounded built-in resolver. It never contains environment values, session
 paths, prompts, or file contents.
 
-New mutation history records failed or explicitly unavailable configured
-resolver outcomes under `context.agent_provenance_outcomes`; dimensions with
+New mutation history records successful probes, failed probes, and explicitly
+unavailable configured resolver outcomes under `context.agent_provenance_outcomes`; dimensions with
 no configured resolver retain the compact legacy-compatible null projection.
 A resolver is only counted as
 attempted when its required input belongs to the detected harness; a foreign
@@ -138,7 +139,30 @@ host's shared `AI_AGENT` value is not Codex input. Consequently `pm health` can
 `provenance_resolver_zero_success:<harness>:<dimension>:<resolver>:<attempts>`
 without confusing an unavailable harness signal with a failed resolver. The
 warning is advisory and the storage check includes the bounded attempt and
-success counters for diagnosis.
+success counters for diagnosis. Resolved environment, session, client, and
+inferred observations do not count as probe successes merely because that
+harness declares a resolver. Existing immutable records are preserved; a new
+successful probe clears an all-failed advisory when the complete sample includes
+that event.
+
+`scanProvenanceResolverHealth()` from `@unbrained/pm-cli/sdk/governance` returns
+`sample`, also exposed as `checks[name=storage].details.provenance_sample` by
+`pm health --full --json`. The receipt declares `scope=history_prefix`, the
+10,000-event and 8 MiB ceilings, events/bytes read, truncation, unreadable sources, malformed rows,
+and the earliest/latest valid event timestamps inspected. Files are traversed
+by sorted name and events by append order: this is a bounded history prefix,
+not a rolling recent window. Timestamp bounds describe observed events only.
+`sample.complete=false` suppresses population-wide zero-success conclusions;
+`truncated` separately identifies byte/event limits. Missing or malformed input
+is diagnosed by the integrity checks. An empty or unavailable-only sample is
+not proof that a resolver works. These measurements describe the sampled
+history, not current probe availability or an unobserved historical success.
+The optional `eventLimit` argument must be a non-negative safe integer;
+invalid bounds throw `RangeError`, and zero requests an empty bounded sample.
+
+The `ProvenanceResolverHealthScan` TypeScript result adds a required `sample`
+receipt. Consumers that construct this result themselves must supply the receipt;
+consumers that only read returned scans retain all prior fields unchanged.
 
 Older immutable history can also contain roles outside the controlled domain,
 including values recorded from presence-only harness flags before semantic role

package/docs/SDK_LIFECYCLE.md

@@ -1,8 +1,9 @@
 # SDK Lifecycle Policy
 
 Tracked by [pm-z5pmf8](../.agents/pm/issues/pm-z5pmf8.toon),
-[pm-xm0id4](../.agents/pm/issues/pm-xm0id4.toon), and
-[pm-2ew0w3](../.agents/pm/issues/pm-2ew0w3.toon).
+[pm-xm0id4](../.agents/pm/issues/pm-xm0id4.toon),
+[pm-2ew0w3](../.agents/pm/issues/pm-2ew0w3.toon), and
+[pm-scbr0s](../.agents/pm/issues/pm-scbr0s.toon).
 
 The public SDK owns lifecycle transactions and policy. CLI and MCP operations
 delegate to SDK modules, so an item does not gain different storage,
@@ -39,6 +40,10 @@ Package authors can import these operations from `@unbrained/pm-cli/sdk`
 without importing CLI modules or spawning the executable. Existing CLI import
 paths remain source-compatible while integrations migrate.
 
+See [Concurrent Workspace Mutations](WORKSPACE_CONCURRENCY.md) for settings
+snapshot reconciliation, schema publication, session locks, and checkpoint
+collision semantics shared by these operations.
+
 ## Relationship Identity
 
 Tracked by [pm-olcoon](../.agents/pm/issues/pm-olcoon.toon).
@@ -94,6 +99,15 @@ An embedded SDK consumer can explicitly choose `orderingEdges: "remove"` for
 a domain where predecessor facts are intentionally ephemeral. The CLI and MCP
 do not expose that override and use the durable default.
 
+Explicit removal returns `closed_removed_predecessors:<item>:<ids>` for the
+complete removed row set and `closed_removed_predecessors_count:<item>:<n>`
+for its cardinality. The count is the number of dependency rows, including
+distinct provenance rows that reference the same item. Clearing a transient
+`blocked_by` scalar is reported separately as
+`closed_cleared_blocked_by:<item>:<blocker>` and does not inflate that count.
+Both removal and its receipts use the same selected rows; other relationship
+kinds survive unchanged.
+
 ```ts
 import {
   closeItem,

package/docs/WORKSPACE_CONCURRENCY.md

@@ -0,0 +1,67 @@
+# Concurrent Workspace Mutations
+
+Tracked by [pm-bgcu](../.agents/pm/issues/pm-bgcu.toon). Power-loss durability is
+governed by [pm-o2kc](../.agents/pm/epics/pm-o2kc.toon).
+
+The CLI and MCP use the SDK's persistence primitives. Atomic replacement makes
+one file write indivisible, but preserving concurrent edits also requires
+protecting the read and decision that precede that write.
+
+## Settings snapshots
+
+`readSettings` attaches an internal, non-enumerable persistence snapshot.
+`writeSettings` compares the caller's edited snapshot with the latest document
+while holding the `workspace-history` lock. Changes to different object keys
+are combined, including separate keys in a newly introduced nested object.
+Unchanged keys keep the current persisted values; sparse defaults and
+file-backed schema definitions remain sparse.
+
+Concurrent incompatible edits to the same scalar, array, or deleted object
+return a conflict before writing. Read a fresh settings snapshot and reapply
+the intended operation. Equal concurrent changes are idempotent. A successful
+write advances that instance's baseline, so reusing it cannot replay an earlier
+edit over another writer. Conflict messages name keys without exposing values.
+Deleting the settings document also invalidates an unchanged read snapshot;
+its next write returns the same structured conflict.
+
+Keep the object returned by `readSettings` when editing settings. Constructing
+a new object, spreading it, or using `structuredClone` drops the internal
+snapshot; `writeSettings` treats such objects as explicit whole-document
+replacements. They are suitable for initialization, not concurrent edits.
+
+The same lock protects the persisted document, its workspace history entry,
+and compensation if history append fails. This prevents concurrent writers
+from forking the chain or leaving an accepted write unrecorded. It does not
+claim crash atomicity across separate filesystem writes.
+
+## Schema, session, and rollback state
+
+Schema mutations hold the existing `schema-types`, `schema-statuses`, or
+`schema-fields` lock while reading and modifying their file. Profile application
+uses the same lock order. Bootstrap stages complete seed bytes and publishes
+them through a non-replacing hard link: a concurrent schema writer or reader
+can never be overwritten by a delayed bootstrap. A filesystem that refuses
+hard links returns an error instead of falling back to an unsafe overwrite.
+
+Focus and semantic attribution share the `session-state` lock across the full
+read-modify-write operation. Independent agents retain their attribution while
+focus changes. This state remains local and ephemeral.
+
+Rollback checkpoints use the same atomic, non-replacing publication as schema
+seeds. Filesystem identity also protects paths reached through symlink aliases.
+A byte-identical retry succeeds; reusing an ID for different contents fails without
+replacing the original rollback evidence. Different checkpoint paths remain
+independent.
+
+Atomic publication guarantees complete visible bytes and prevents replacement.
+It does not flush file data or directory entries to stable storage, so success
+does not guarantee survival of power loss. A stronger durability policy must
+cover all writers, newly created ancestor directories, retry acknowledgements,
+and supported filesystems; syncing only this publication path would not establish
+that workspace-wide guarantee.
+
+The mutation locks use the existing bounded contention and stale-owner recovery
+mechanism. Settings use configured lock TTL and wait values. Internal session
+locks use the standard defaults; `PM_LOCK_WAIT_MS` still
+overrides their wait budget. Every acquired lock is released on success and
+failure.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -222,7 +222,7 @@
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@sentry/cli": "^3.8.0",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.9.18",
+  "version": "2026.9.19",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",