@unbrained/pm-cli 2026.8.17 → 2026.8.19

package/docs/COMMANDS.md

@@ -2,7 +2,7 @@
 
 This is a task-oriented command guide. For exact flags, use runtime help because extensions and settings can change the active surface:
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), positional action discovery [pm-2tan](../.agents/pm/issues/pm-2tan.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
 Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
 
@@ -141,8 +141,8 @@ pm search "calendar reminder validation" --limit 10
 pm get pm-a1b2                          # read one item; add --fields/--depth for lower-token projections
 pm get pm-a1b2 --tree --tree-depth 2    # item plus its descendant subtree
 pm get pm-a1b2 --at 7                   # verified, mutation-free historical version
-pm list-open --type Task --priority 1 --limit 20
-pm list-in-progress --limit 20
+pm list --status open --type Task --priority 1 --limit 20
+pm list --status in_progress --limit 20
 pm aggregate --group-by parent,type --status open
 pm aggregate --group-by parent,type --completion --include-unparented
 pm duplicates --status all --threshold 0.8
@@ -173,7 +173,7 @@ Each aggregate row carries an explicit `group_label`: a blank/null group value (
 `--sort` accepts `priority|deadline|updated_at|created_at|title|parent`, plus the convenience aliases `updated` (→ `updated_at`) and `created` (→ `created_at`):
 
 ```bash
-pm list-all --sort updated --order desc
+pm list --all --sort updated --order desc
 ```
 
 ### Incremental "what changed since" filters
@@ -182,16 +182,16 @@ Every `list*` command accepts `--updated-after`/`--updated-before`/`--created-af
 
 ```bash
 # Items touched since my last context window (feed back the previous run's `now`)
-pm list-all --updated-after 2026-06-04T15:18:32Z --brief
+pm list --all --updated-after 2026-06-04T15:18:32Z --brief
 
 # Relative offsets are SIGNED: -2h/-7d reach into the past, +1d into the future.
 # Units are h/d/w/m (m = months — there is no minutes unit).
-pm list-open --updated-after=-2h --brief
-pm list-all --created-after=-7d --status open
+pm list --status open --updated-after=-2h --brief
+pm list --status open --created-after=-7d
 
-# Common list windows avoid date math (`list-open` keeps the view open-only).
-pm list-open --today --brief
-pm list-all --recent --brief
+# Common list windows avoid date math (`pm list --status open` keeps the view open-only).
+pm list --status open --today --brief
+pm list --all --recent --brief
 
 # Search scoped to open work only (drops closed-history noise); statuses accept
 # all (no lifecycle restriction), open/closed/canceled aliases, or configured
@@ -293,12 +293,12 @@ pm eval --fail-under 0.6 --json      # CI gate: exit non-zero when aggregate nDC
 
 ### Full results, totals, and bodies
 
-`pm list*` returns every matched row when neither `--limit` nor `--offset` is set. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. `completeness` reports whether the corpus was `complete`, `partial`, or `unchecked` (derived-index page), with unreadable item/directory counts. Use `--strict-read` when omissions must fail the command. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` (alias `--all`) to force the entire matched set and override any `--limit` in one call — the canonical "give me everything" flag for large-corpus audits:
+`pm list` returns every matched row when neither `--limit` nor `--offset` is set. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. `completeness` reports whether the corpus was `complete`, `partial`, or `unchecked` (derived-index page), with unreadable item/directory counts. Use `--strict-read` when omissions must fail the command. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` to force the entire matched set and override any `--limit` in one call. `--all` selects every lifecycle status; combine the flags for an unbounded all-status audit:
 
 ```bash
-pm list-all --no-truncate --brief          # every matched row, ignoring any --limit
-pm list-open --limit 20 --json             # stable total/has_more/truncated/next_cursor envelope
-pm list-all --strict-read --json           # fail if any source item cannot be read
+pm list --all --no-truncate --brief        # every matched row, ignoring any --limit
+pm list --status open --limit 20 --json    # stable total/has_more/truncated/next_cursor envelope
+pm list --all --strict-read --json         # fail if any source item cannot be read
 ```
 
 Compatibility note: older responses emitted `total` only when pagination
@@ -312,7 +312,7 @@ unconditional pre-pagination match count, branch on `has_more` or
 JSON output is compact by default (id/status/type/title) for token efficiency. To pull item bodies in bulk in a single call — instead of one `pm get` per item — add `--include-body`, which expands each row to the full field set plus `body`:
 
 ```bash
-pm list-open --json --include-body         # full fields + body for every returned row
+pm list --status open --json --include-body # full fields + body for every returned row
 ```
 
 `pm get <id> --json` returns the item's `body` **inside** the `item` object (i.e. `.item.body`), matching where `list --include-body` places it and the long-form `description`/`acceptance_criteria` fields — so a single read exposes every field at a consistent path. Body is included at the default `standard` depth and above; `--depth brief` omits it.
@@ -322,10 +322,10 @@ pm list-open --json --include-body         # full fields + body for every return
 `pm list*` accepts `--format <csv|table|json|ndjson|toon>` to choose how rows render. `csv` and `table` are **human export** modes — pipe them into a spreadsheet or read them directly in a terminal — while `json`/`toon` override the machine output format the same way the global `--json` flag does. `ndjson` writes each projected item as one self-contained JSON object per line, with no wrapper or trailing summary. The rendered fields follow the active projection, so combine `--format` with `--fields`/`--brief`/`--compact` to control exactly what appears:
 
 ```bash
-pm list-open --format table                      # aligned, monospace-friendly columns
-pm list-all --fields id,title,priority --format csv  # spreadsheet export with chosen columns
-pm list-open --format csv > backlog.csv          # capture for reporting
-pm list-all --brief --format ndjson | jq -c 'select(.status == "open")'
+pm list --status open --format table                 # aligned, monospace-friendly columns
+pm list --all --fields id,title,priority --format csv # spreadsheet export with chosen columns
+pm list --status open --format csv > backlog.csv     # capture for reporting
+pm list --all --brief --format ndjson | jq -c 'select(.status == "open")'
 ```
 
 CSV output is RFC 4180 compliant (values with commas, quotes, or newlines are quoted; array fields such as `tags` join with `;`). `--format csv|table|ndjson` cannot be combined with the legacy envelope-oriented `--stream` mode.
@@ -338,13 +338,13 @@ The same `list*` commands and `pm search` extend this with governance-field pres
 
 ```bash
 # Find open Tasks that still need acceptance criteria
-pm list-open --type Task --filter-ac-missing --brief
+pm list --status open --type Task --filter-ac-missing --brief
 
 # Closed items that were never given a resolution
-pm list-closed --filter-resolution-missing --json
+pm list --status closed --filter-resolution-missing --json
 
 # Open items that still need a reviewer assigned
-pm list-open --filter-reviewer-missing --brief
+pm list --status open --filter-reviewer-missing --brief
 ```
 
 ### Content-field presence filters
@@ -353,10 +353,10 @@ pm list-open --filter-reviewer-missing --brief
 
 ```bash
 # Closed items that shipped no documented learnings
-pm list-closed --no-learnings --brief
+pm list --status closed --no-learnings --brief
 
 # Open work that has linked tests but no linked files yet
-pm list-open --has-tests --no-files --json
+pm list --status open --has-tests --no-files --json
 ```
 
 ## Bulk Operations
@@ -1120,6 +1120,13 @@ Profiles are extensible: a package can ship its own archetype with `api.register
 
 Plan creation shares the normal create contract. Governance fields such as `--status`, `--deadline`, `--estimate`, `--acceptance-criteria`, `--assignee`, review/risk fields, comments, notes, learnings, reminders, events, and linked resources are accepted directly and pass through the same strict/progressive schema validation as `pm create`.
 
+Every positional plan action is also a discoverable virtual command path. Use
+`pm plan create --help --json` or `pm help plan create --json` for its exact
+arguments and effective flags, and use `pm contracts --command "plan create"
+--flags-only --json` for the matching machine contract. Root `pm plan --help
+--json` publishes the same action inventory under `subcommands`; omitting the
+required action fails as `missing_required_argument` before mutation dispatch.
+
 ```bash
 pm plan create --title "Refactor lock retry" --scope "Improve retry semantics" --harness claude-code --parent pm-epic1 --related pm-rel1,pm-rel2 --claim
 pm plan create --title "Fix flaky retry test" --step "Read lock.ts" --step "Write the fix" --step "Run the tests"
@@ -1190,9 +1197,14 @@ Project-governance setters use the separate `governance_contracts` value
 domains; in particular, workflow enforcement is `off|warn|strict`, not the
 extension policy token `enforce`.
 Use `pm contracts --summary --json` first when bootstrapping in a tight context
-window. `command_summaries` contains exactly one row per advertised command
-path—including aliases and namespace children—with a meaningful intent plus
-`default_max_estimated_tokens` and the format-specific TOON/JSON ceilings.
+window. `command_summaries` contains one row per registered command path,
+including aliases and namespace children, with a meaningful intent plus
+`default_max_estimated_tokens`. The low-token summary intentionally does not
+repeat the 32 virtual positional Plan, Assurance, and workspace-snapshot action rows;
+`grammar_contracts.positional_action_count` and `positional_action_parents`
+retain their complete discoverability and route callers to root help. A
+command-scoped contract for an exact action restores its typed positional
+signature, exact flags, provenance, and format-specific TOON/JSON ceilings.
 Package commands contribute their intent through command registration (falling
 back to the registered description), so agents never need a generic
 `Inspect flags.` placeholder. Request heavier command-specific flags or schemas

package/docs/ONBOARDING.md

@@ -41,8 +41,8 @@ Use progressive disclosure:
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 pm install guide-shell --project
 pm guide workflows
 ```
@@ -82,8 +82,8 @@ The canonical loop is maintained in [AGENT_GUIDE.md](AGENT_GUIDE.md) — this is
 ```bash
 pm context --limit 10
 pm search "<keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 2. Claim and start

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -15,7 +15,8 @@ selectors are tracked by
 [pm-x710qm](../.agents/pm/issues/pm-x710qm.toon). Default contract suppression
 and canonical TOON tables are tracked by
 [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
-[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon).
+[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon). Nested evidence continuation
+is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon).
 
 ## Agent Quick Context
 
@@ -73,6 +74,7 @@ or not the current page has rows:
     "command": "list",
     "row_kind": "collection",
     "row_keys": ["items"],
+    "continuation_row_keys": ["items"],
     "fields": "supported",
     "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end",
     "toon_encoding": "tabular_when_uniform"
@@ -89,6 +91,12 @@ nested dependency graph and relationship-context rows addressable as
 `graph.nodes`, `graph.edges`, `context.nodes`, and `context.edges` without
 duplicating them at the envelope root. Array collections produce their
 elements; object maps produce jq `to_entries` rows.
+`continuation_row_keys` is optional and defaults to `row_keys`. A command uses
+it only when independently resumable nested evidence differs from its primary
+amount-bounded rows. Validate, for example, keeps `checks` and `warnings` as
+primary rows while a rich result can name
+`checks.0.details.missing_resolution_rows` as a continuation row. This prevents
+an inner diagnostic array from disabling `--output-limit` on the outer checks.
 `toon_encoding: "tabular_when_uniform"` declares that an array of flat objects
 with one shared key set renders as a length-marked TOON table; mixed, nested,
 or heterogeneous arrays retain the expanded representation. Quoted,
@@ -107,7 +115,8 @@ publish a row contract.
 SDK and package authors can import `PM_READ_ROW_CONTRACTS`,
 `PM_READ_ROW_JQ_SELECTOR`, and `resolveReadRowContract` from
 `@unbrained/pm-cli/sdk`. Existing package declarations are preserved only
-when `command`, `row_kind`, `row_keys`, `fields`, the conditional
+when `command`, `row_kind`, `row_keys`, optional unique non-empty
+`continuation_row_keys`, `fields`, the conditional
 `jq_selector`, and any supplied `toon_encoding` form a structurally valid row contract; malformed declarations
 are replaced by the canonical built-in contract when one applies.
 

package/docs/QUICKSTART.md

@@ -94,7 +94,7 @@ Useful item types:
 ```bash
 pm context --limit 10
 pm search "restore lock retry" --limit 10
-pm list-open --limit 20
+pm list --status open --limit 20
 pm claim <item-id>
 pm update <item-id> --status in_progress --message "Start implementation"
 pm update <item-id> --add-tags urgent,backend

package/docs/README.md

@@ -40,9 +40,11 @@ pm guide release --json
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Security Governance](SECURITY_GOVERNANCE.md) - vulnerability reporting, review discipline, property fuzzing, and OpenSSF limitations.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
+- [Noun–Verb CLI Grammar](CLI_GRAMMAR.md) - accepted command architecture, exhaustive destination census, hidden aliases, and the surface-growth gate.
 - [SDK Primitive Inventory](SDK_PRIMITIVE_INVENTORY.md) - SDK-first migration map and private-import ratchet for CLI/MCP layering.
 - [Package SDK Contract Conformance](PACKAGE_SDK_CONTRACT_CONFORMANCE.md) - authoritative public types, `typeof` module derivation, and the first-party parity gate.
 - [SDK Action and Boundary Conformance](SDK_ACTION_CONFORMANCE.md) - derived CLI/SDK/MCP action vocabulary, public-import ratchets, intent budget diagnostics, and package-runner proof.
+- [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -15,10 +15,13 @@ Every built-in read surface uses four output dimensions: what to include, how mu
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
-Row shaping follows each envelope's `row_contract.row_keys`, including
-dot-delimited nested arrays and object maps such as `graph.nodes`. Include,
-amount, repeat suppression, and cost compaction therefore operate on the same
-machine-declared rows; they do not rely on command-specific top-level keys.
+Primary row shaping follows each envelope's `row_contract.row_keys`, including
+dot-delimited arrays and object maps such as `graph.nodes`. Include, amount, and
+repeat suppression therefore remain bound to the rows the command says it
+returns. A result may additionally declare `continuation_row_keys` when a
+nested evidence collection must resume independently without redefining the
+primary rows that `--output-limit` bounds. Cost compaction may inspect both
+primary and nested collections; it does not rely on command-specific keys.
 The runtime uses that declaration internally on every read but omits the
 repeated metadata from results by default. Request
 `--output-row-contract` / `outputRowContract: true` when a consumer needs the
@@ -153,8 +156,9 @@ producer cursor, a universal output cursor, and a terminal page;
 `next_cursor` mirrors the first universal entry for ordinary one-path
 consumers. Replay the same query and budget
 with `--output-cursor <cursor>` / `outputCursor`. The cursor validates the
-command, declared row path, total, and stable row identities before slicing, so
-a mismatched or stale replay fails closed instead of skipping evidence. A
+command, declared continuation path, total, and canonical content fingerprint
+before slicing, so same-cardinality content changes and other stale replays
+fail closed instead of skipping evidence. A
 bounded recovery therefore does not require replacing a 600-token request with
 an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same

package/docs/RELEASING.md

@@ -27,7 +27,8 @@ The local/hosted gate selection contract is tracked by
 [pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon). Release-candidate analyzer
 provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon), and
 authoritative blocker-recovery run selection by
-[pm-db8onn](../.agents/pm/issues/pm-db8onn.toon).
+[pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
+same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
 
 ## Version Policy
 
@@ -78,11 +79,11 @@ Policy:
   created, a non-`github-actions[bot]` closure of the exact bot-created
   `Auto Release blocked` issue on the same UTC day triggers one preparation
   retry
-- if today's tag already exists, blocker closure bypasses release-preparation
-  provenance, dependency installation, and build work, then selects immutable
-  Release evidence across both tag-push and guarded workflow-dispatch runs; a
-  completed success is authoritative over stale failures and is recorded as
-  recovered without republishing
+- if today's tag already exists, a queued schedule or blocker closure bypasses
+  candidate preparation and accepts the immutable result only after independent
+  public-distribution evidence confirms the exact release; incomplete
+  publication continues through bounded recovery instead of being accepted
+  from tag presence alone
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - before dependency installation or build, auto-release verifies that the
   candidate has exact-commit analyzer results or an immutable tree-identical
@@ -104,6 +105,10 @@ Policy:
   before release mutation and reported as `retry_already_attempted`, and
   workflow cleanup closures by `github-actions[bot]` are ignored.
 - after a scheduled run publishes a tag and the downstream release workflow succeeds, auto-release closes any open `Auto Release blocked` issue so the GitHub tracker reflects current release health
+- workflow concurrency can leave a delayed schedule queued behind another
+  production run. The queued schedule resolves the current UTC-day immutable
+  result before candidate provenance, proves publication, and exits without
+  evaluating the generated release commit as a new candidate
 
 Pipeline entrypoint:
 
@@ -268,6 +273,25 @@ confirms that exact merge SHA, `main` base, and reviewed head. Remediate a
 refused direct-main candidate by landing the next tree-changing fix through a
 reviewed PR; never copy, synthesize, or bypass analyzer evidence.
 
+### Reviewed Delivery Closeout
+
+The reviewed delivery includes its PM evidence, item closure, and generated
+changelog. Complete those mutations on the implementation branch before merge
+whenever their evidence is already available. A pull request is not complete
+while known tracker or changelog closeout remains queued for a direct push.
+
+When a repository update genuinely depends on the merge SHA or a post-merge
+hosted result, create a normal follow-up branch from `main` and land that update
+through another reviewed pull request. Do not push `.agents/pm/**` or
+`CHANGELOG.md` closeout directly to `main`. Although tracker-only commits do not
+create package-release eligibility by themselves, the direct commit still
+becomes the default-branch head and lacks the reviewed analyzer evidence needed
+by the next release-relevant candidate. `Release analyzer readiness (main)`
+must fail closed in that state; its failure is a provenance control, not an
+analyzer approval. Restore readiness only with a tree-changing, `main`-based,
+reviewed pull request—never by copying statuses, weakening the gate, or
+synthesizing a pull-request association.
+
 ```bash
 # Read-only parity check
 pnpm release:pipeline:dry-run

package/docs/SDK.md

@@ -47,6 +47,13 @@ first-class recurrence relationships are tracked by
 [pm-rf120g](../.agents/pm/tasks/pm-rf120g.toon),
 [pm-3crymx](../.agents/pm/issues/pm-3crymx.toon), and
 [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon).
+Fail-closed whole-corpus reads and package-catalog output controls are tracked by
+[pm-y4aaol](../.agents/pm/issues/pm-y4aaol.toon) and
+[pm-2firut](../.agents/pm/issues/pm-2firut.toon).
+Positional command signatures, action-scoped discovery, and MCP/CLI option
+parity are tracked by [pm-ya7x55](../.agents/pm/tasks/pm-ya7x55.toon),
+[pm-2tan](../.agents/pm/issues/pm-2tan.toon), and
+[pm-y0htkd](../.agents/pm/issues/pm-y0htkd.toon).
 
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
@@ -199,6 +206,7 @@ Source of truth:
 - [`src/sdk/merge/index.ts`](../src/sdk/merge/index.ts)
 - [`src/sdk/workspace-transaction-gc.ts`](../src/sdk/workspace-transaction-gc.ts)
 - [`src/sdk/query/list.ts`](../src/sdk/query/list.ts)
+- [`src/sdk/query/complete-list.ts`](../src/sdk/query/complete-list.ts)
 - [`src/sdk/query/search.ts`](../src/sdk/query/search.ts)
 - [`src/sdk/query/search-pagination.ts`](../src/sdk/query/search-pagination.ts)
 - [`src/sdk/query/search-rendering.ts`](../src/sdk/query/search-rendering.ts)
@@ -292,7 +300,7 @@ Storage format-version exports (under `@unbrained/pm-cli/sdk/runtime`):
 Command/action contract exports:
 
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
-- Typed read primitives on `PmClient`: `get` (including `GetOptions.at` point-in-time reads), `list`, `search`, `context`, `next`, `aggregate`, `stats`, and `duplicates`; direct `getItemAt` reconstructs a canonical historical document without mutation. `duplicates` performs one bounded all-status metadata sweep and returns deterministic canonical-candidate and close-command guidance without mutating items.
+- Typed read primitives on `PmClient`: `get` (including `GetOptions.at` point-in-time reads), `list`, `listAllComplete`, `search`, `context`, `next`, `aggregate`, `stats`, and `duplicates`; direct `getItemAt` reconstructs a canonical historical document without mutation. `listAllComplete` forces an all-status, full, strict, unbounded read and fails closed unless the returned envelope proves source completeness, unique ids, exact counts, no pagination, no field or budget omission, and no session projection. `duplicates` performs one bounded all-status metadata sweep and returns deterministic canonical-candidate and close-command guidance without mutating items.
 - Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`. Standard and brief `get` projections omit note bodies but expose `item.notes_count`; deep/full reads return the notes themselves, and narrow consumers can request `notes_count` explicitly.
 - Stream projection primitive: `serializeNdjsonRows` frames SDK-owned object rows as newline-delimited JSON without a trailing newline and rejects scalar/array rows, so package transports can match list/search/context CLI semantics without importing presentation code.
 - Context relevance primitives: `buildItemContextRelevanceCandidates`, `buildContextSignalSnapshot`, `ContextSignalStore`, `JsonFileContextSignalStoreAdapter`, `parseContextSignalSnapshot`, `defaultScoreContextCandidates`, `scoreContextCandidates`, `scoreContextCandidatesWithActiveExtensions`, `evaluateContextRanking`, `runContextEvaluationScenario`, `runContextEvaluationCorpus`, and `summarizeContextEvaluationReports`
@@ -336,6 +344,8 @@ Command/action contract exports:
 - Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
 - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
 - Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry`, `resolveMissingOptionPlaceholder`, and `resolveRecoveryCommandName` preserve attempted argv, derive enum/boolean/scalar recovery arity from flag contracts, and identify the actual command without mistaking a global option value for one; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Positional grammar primitives: `PM_COMMAND_POSITIONAL_CONTRACTS` declares every core and known-package command signature as ordered, typed slots; `PM_POSITIONAL_ACTION_CONTRACTS` promotes positional plan and assurance actions into discoverable virtual command paths with action-scoped flags, examples, and intent. `resolvePmCommandPositionalContract`, `resolvePmPositionalActionContract`, and `verifyPmCommandPositionalContracts` let custom hosts resolve or fail-closed compare the same signatures emitted by runtime contracts. The grammar receipt ratchets distinct semantic shapes through `positional_shape_budget` so a new arity cannot silently expand agent context.
+- MCP/CLI option parity primitive: `verifyToolOptionCliParity` compares one `ToolOptionFlagContract` table with its executable `CliFlagContract` table. It fails when the transport-selected canonical flag is absent or when a parameter such as `linkedFile` cannot be invoked using its kebab-case CLI spelling (`--linked-file`) canonically or through a registered alias. Core create/update parity is part of the required command-grammar gate.
 - Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
@@ -1468,6 +1478,10 @@ helpers return `ExtensionCommandResult`; both names describe the same lifecycle
 payload shape with vocabulary-appropriate SDK signatures. `UpgradeResult` is the
 same structured payload rendered by the CLI, so embedded tools can own their
 presentation layer while sharing pm's package/install/doctor semantics.
+`packageCatalog` is a read surface and accepts the universal output controls;
+the CLI-equivalent `pm --output-budget unbounded package --catalog --json`
+therefore composes with the same output contract while catalog-plus-mutation
+invocations fail before any package state can change.
 
 Annotation and relationship convenience methods turn "project management =
 context management" into a typed SDK surface. Use `pm.comments`, `pm.notes`,
@@ -1576,9 +1590,35 @@ compact or `fields` projections return `ListProjectedItem` dictionaries. Use
 a `partial` scan with unreadable item/directory counts, and an `unchecked`
 derived-index page. Set `ListOptions.strictRead` (CLI `--strict-read`) when an
 automation must fail instead of accepting omissions.
-`full: true` when an integration requires complete item metadata; the overload
+Use `full: true` when an integration requires complete item metadata; the overload
 then returns `ListFullResult` without an assertion or cast.
 
+When correctness depends on the entire workspace rather than a page, use the
+certifying primitive instead of rebuilding these conditions at every call site:
+
+```ts
+import {
+  PmClient,
+  certifyCompleteListResult,
+  createCompleteListOptions,
+} from "@unbrained/pm-cli/sdk/runtime";
+
+const pm = new PmClient({ pmRoot: "/workspace/.agents/pm" });
+const corpus = await pm.listAllComplete({ includeBody: true });
+corpus.complete_list.source_complete; // true, otherwise the call throws
+
+// Custom transports can apply the same request and certificate independently.
+const candidate = await pm.list(createCompleteListOptions());
+const certified = certifyCompleteListResult(candidate);
+```
+
+`PmCompleteListValidationError.receipt` lists every failed invariant and carries
+the exact recovery command
+`pm list-all --full --strict-read --no-truncate --output-budget unbounded --json`.
+The helper never infers completeness from a large limit: derived-index reads,
+terminal-state filtering, duplicate ids, cursor/session projection, compaction,
+and any omission receipt all prevent certification.
+
 CLI JSON consumers can add `--lean` to compact null and empty values. On
 item-list envelopes, lean output also removes request echoes (`filters`, `now`,
 `projection`, and `sorting`) and removes `next_cursor` when `has_more` is not

package/docs/SDK_ARTIFACT_OUTPUT.md

@@ -0,0 +1,72 @@
+# SDK artifact output contracts
+
+Trackers: [pm-dilou2](../.agents/pm/issues/pm-dilou2.toon) and [pm-mav1ak](../.agents/pm/features/pm-mav1ak.toon).
+
+Exporter artifacts are data streams, not command receipts. A package declares
+the channel when it registers an exporter so the host never guesses whether a
+returned value should be appended to artifact bytes.
+
+## Agent quick context
+
+- Declare `output.channel: "stdout"` for JSON, NDJSON, CSV, or opaque bytes.
+  The host suppresses its receipt by default, including under global `--json`.
+- Declare `output.channel: "file"` when the exporter writes a file. The host
+  renders the returned bounded receipt by default.
+- An exporter may still return a structured result. Suppressed receipts remain
+  available to hooks, telemetry, and embedding hosts.
+- Write optional human progress or summaries to stderr. Never mix them into a
+  stdout artifact.
+- Legacy registrations without `output` retain their previous rendering.
+
+## Registration
+
+```ts
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
+
+export function activate(api: ExtensionApi): void {
+  api.registerExporter(
+    "report-json",
+    async () => {
+      process.stdout.write('{"items":[]}\n');
+      return { exported: 0 };
+    },
+    {
+      description: "Export a complete JSON report to stdout.",
+      output: {
+        channel: "stdout",
+        media_type: "application/json",
+      },
+    },
+  );
+}
+```
+
+The normalized contract is visible in the extension contribution inventory.
+Derived help also states that stdout artifact bytes are exclusive and host
+receipt rendering is suppressed when the extension does not supply a custom
+description.
+
+## Channel behavior
+
+| Artifact channel | Default receipt | stdout | stderr |
+| --- | --- | --- | --- |
+| `stdout` | `suppress` | Artifact bytes only | Extension-owned diagnostics or summary |
+| `file` | `render` | Bounded structured receipt | Extension-owned diagnostics |
+
+File exporters may select `receipt: "render"` or `receipt: "suppress"` as an
+explicit compatibility control. Stdout artifacts always suppress the host
+receipt; declaring `receipt: "render"` with `channel: "stdout"` is rejected at
+registration so redirection, `jq`, and binary output remain clean by
+construction.
+
+The host does not decode, re-encode, buffer, or inspect stdout artifact bytes.
+Consequently NUL bytes and non-UTF-8 payloads pass through unchanged. The
+extension owns media correctness and stream completion; the host owns only the
+post-handler receipt policy.
+
+## Shared NDJSON framing
+
+SDK-built producers can use `serializeNdjsonStream(rows, trailer)` to append one
+typed `pm.stream.trailer` after a bounded row batch. It supplies one stable
+place for counts, continuation cursors, source identity, and constant-size
+producer metadata without adding per-row overhead.

package/docs/SDK_CONTEXT_COORDINATION.md

@@ -1,6 +1,6 @@
 # SDK context coordination primitives
 
-Trackers: [pm-e200](../.agents/pm/features/pm-e200.toon), [pm-4ri6](../.agents/pm/features/pm-4ri6.toon), and [pm-hcrmye](../.agents/pm/issues/pm-hcrmye.toon).
+Trackers: [pm-e200](../.agents/pm/features/pm-e200.toon), [pm-ez1dfg](../.agents/pm/tasks/pm-ez1dfg.toon), [pm-4ri6](../.agents/pm/features/pm-4ri6.toon), and [pm-hcrmye](../.agents/pm/issues/pm-hcrmye.toon).
 
 `pm` treats project management as context management. These primitives let an
 agent learn what changed, avoid creating redundant work, and keep that work
@@ -26,38 +26,72 @@ Read committed history facts as newline-delimited JSON:
 pm events --type create --author agent-a --limit 100
 pm events --since <cursor> --item pm-abcd
 pm events --since <cursor> --follow --interval-ms 250
+pm events --cursor-mode row --since <cursor>
 ```
 
-Each line carries `cursor`, `item_id`, `version`, `ts`, `author`, `type`, and
-`patch_count`; `--full` also includes the complete authoritative history entry.
+By default, event rows carry `item_id`, `version`, `ts`, `author`, `type`, and
+`patch_count`, followed by one `pm.stream.trailer` record with `count`,
+`has_more`, `next_cursor`, and `source`. Persist the trailer cursor only after
+the batch is durable. A crash before cursor persistence can replay the last
+batch repeatedly, including across multiple crashes. Consumers must process
+idempotently or deduplicate replays. `--cursor-mode row` preserves the previous
+shape with one `cursor` per event and no trailer for consumers that checkpoint
+every row. Already issued version-1 cursors remain accepted by `--since`.
+
+Node runtimes use the rebuildable SQLite event projection. Runtimes such as Bun
+that do not expose `node:sqlite` transparently scan the authoritative history
+streams with the same ordering, filters, pagination, and cursor contract; pages
+identify that path with `source: "authoritative_history"`.
+
+`--full` also includes the complete authoritative history entry.
 `--type`, `--author`, and `--item` accept repeatable or comma-separated values.
 `--since` accepts either a cursor or an ISO timestamp. The CLI emits only event
-rows, so it composes directly with standard NDJSON consumers.
+rows and the typed terminal record, so consumers can distinguish data from
+recovery metadata without relying on position alone. Under `--follow`, every
+non-empty page ends at the same batch boundary and an empty boundary is emitted
+as an idle heartbeat.
 
 The public SDK provides bounded pages and an abortable async iterator:
 
 ```ts
 import {
   listMutationEvents,
+  subscribeMutationEventBatches,
   subscribeMutationEvents,
 } from "@unbrained/pm-cli/sdk";
 
-const page = await listMutationEvents({
-  pmRoot,
-  type: ["create", "update"],
-  limit: 100,
-});
+const eventTypes = ["create", "update"] as const;
+let cursor: string | undefined;
+let hasMore = true;
+while (hasMore) {
+  const page = await listMutationEvents({
+    pmRoot,
+    type: eventTypes,
+    limit: 100,
+    ...(cursor === undefined ? {} : { since: cursor }),
+  });
+  await consumeBatch(page.events);
+  await persistCursor(page.next_cursor);
+  cursor = page.next_cursor;
+  hasMore = page.has_more;
+}
 
 const controller = new AbortController();
-for await (const event of subscribeMutationEvents({
+for await (const batch of subscribeMutationEventBatches({
   pmRoot,
-  since: page.next_cursor,
+  type: eventTypes,
+  ...(cursor === undefined ? {} : { since: cursor }),
   signal: controller.signal,
 })) {
-  await consume(event);
+  await consumeBatch(batch.events);
+  await persistCursor(batch.next_cursor);
 }
 ```
 
+`subscribeMutationEvents` remains the per-event compatibility iterator and
+defaults to row cursors. `subscribeMutationEventBatches` is the token-efficient
+coordination primitive; it exposes the same boundaries used by the CLI.
+
 The `pm_events` MCP tool exposes the same bounded page contract. Consumers such
 as notification packages can store `next_cursor`, catch up after a restart,
 then follow without requiring a daemon. A pm-slack migration can replace

package/docs/TESTING.md

@@ -2,7 +2,7 @@
 
 This page describes safe local tests, linked tests, coverage, and release-readiness checks.
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon).
 
 ## Agent Quick Context
 
@@ -259,6 +259,19 @@ Do not update the baseline merely to make CI green. Change judgments and
 rationales in the corpus when product intent changes, and commit the corpus,
 baseline, scorer tests, and SDK documentation together.
 
+Context-intent classification has a separate calibration receipt and one
+manifest-backed recovery spelling:
+
+```bash
+pnpm context:intent:calibrate
+pnpm context:intent:calibrate --update
+```
+
+The gate verifies that `package.json` exposes that exact script before it reads
+or refreshes `scripts/release/context-intent-calibration.json`. A missing or
+renamed script therefore fails with the same command contributors are told to
+run, and pnpm forwards `--update` to the calibration gate.
+
 ## Hosted Gate Registry
 
 Tracked by [pm-k6t4yb](../.agents/pm/tasks/pm-k6t4yb.toon) and