@unbrained/pm-cli 2026.8.17 → 2026.8.18

package/docs/CLI_GRAMMAR.md

@@ -0,0 +1,106 @@
+# Noun–Verb CLI Grammar and Compatibility Policy
+
+Tracked by [pm-pbyu](../.agents/pm/decisions/pm-pbyu.toon), implemented through [pm-0z7n](../.agents/pm/features/pm-0z7n.toon), [pm-pfqi](../.agents/pm/tasks/pm-pfqi.toon), [pm-yy8rmx](../.agents/pm/tasks/pm-yy8rmx.toon), and [pm-wt43zj](../.agents/pm/tasks/pm-wt43zj.toon).
+
+## Agent Quick Context
+
+Use the canonical noun-first form when generating commands. Existing spellings remain executable, but deprecated compatibility aliases are absent from default help and completion discovery and emit one migration hint on stderr. Machine clients can read alias lifecycle and replacement tokens from `pm contracts --full --json`.
+
+The first completed consolidation is the list family:
+
+```bash
+pm list                         # active lifecycle rows
+pm list --status open          # one lifecycle class
+pm list --status open,blocked  # several classes
+pm list --status blocked       # status- or dependency-blocked semantics
+pm list --all                  # every lifecycle status
+```
+
+`list-all`, `list-draft`, `list-open`, `list-in-progress`, `list-blocked`, `list-closed`, and `list-canceled` preserve command results and stdout behavior. Their documented migration hint may add one stderr line.
+
+## Status
+
+Accepted. The grammar contract, destination census, and compatibility policy are executable SDK data and mandatory static gates.
+
+## Context
+
+pm grew by adding one top-level spelling per feature. That made help, completions, contracts, documentation, and agent routing grow linearly even when several commands represented the same concept. The list family alone repeated almost the same help surface eight times. A universal project-management tool needs extensible behavior without requiring every agent to memorize an ever-growing flat vocabulary.
+
+The governing product principle is `project management = context management`: command discovery must route an agent to the smallest authoritative context, while compatibility must preserve scripts and historical instructions.
+
+## Decision Drivers
+
+- Preserve every published invocation and its stdout behavior.
+- Keep frequent operations concise without making aliases the discovery model.
+- Make domain ownership explicit enough to generate routing, help, completions, SDK contracts, MCP projections, and documentation.
+- Prevent surface regrowth with a fail-closed, bidirectional contract gate.
+- Let packages add domain behavior without consuming the core noun budget.
+- Make migration guidance suppressible for automation while keeping canonical replacements machine-readable.
+
+## Alternatives Considered
+
+### Flat surface status quo
+
+Rejected. Each feature adds another root spelling and duplicates contract/help context. A byte-count snapshot records growth but does not decide whether the new command belongs in the architecture.
+
+### Pure git-style subcommands
+
+Rejected as an exclusive rule. Noun-first paths are canonical, but forcing high-frequency operations such as `create`, `get`, `update`, `claim`, and `close` to pay an extra token on every invocation would regress the agent hot path. Named permanent aliases may remain visible and are distinguished from deprecated compatibility shims in contract data.
+
+### BusyBox-style multi-binary surface
+
+Rejected. Separate binaries multiply distribution, signing, package resolution, documentation, and shell-discovery surfaces without improving domain routing.
+
+## Decision
+
+1. The core routing vocabulary has twelve nouns: `item`, `list`, `context`, `search`, `graph`, `history`, `workspace`, `package`, `ops`, `plan`, `contracts`, and `help`.
+2. Canonical forms are noun-first. Verbs and facets are subcommands; projections and predicates are flags.
+3. Shared semantics use a shared verb vocabulary. Noun-specific verbs require an explicit checked-in disposition.
+4. Scope precedes its operation: for example, `workspace snapshot create`, not `workspace create snapshot`.
+5. Package-owned commands are declared as such and do not silently expand the core noun set.
+6. Published spellings are not removed. Deprecated spellings are hidden aliases with a canonical token sequence, PM owner, lifecycle, and one stderr migration hint.
+7. Permanent hot-path aliases and deprecated aliases are different contract states. Permanent aliases are ergonomic API; deprecated aliases are compatibility state.
+8. Every live command has exactly one destination row. A row may name its target noun, a tracked consolidation owner, a package owner, or a reasoned keep-as-is exception.
+9. The census is bidirectional: missing live rows and stale checked-in rows both fail CI.
+10. Default-visible top-level growth is ceilinged. Lowering the ceiling is always valid; raising it requires a tracked noun-placement decision rather than regenerating a baseline.
+
+## SDK Contract
+
+Package authors and embedded clients use the public exports:
+
+```ts
+import {
+  PM_CLI_GRAMMAR_CONTRACT,
+  PM_COMMAND_ALIAS_CONTRACTS,
+  PM_COMMAND_DESTINATION_CONTRACTS,
+  resolvePmCommandAlias,
+  verifyPmCliGrammar,
+} from "@unbrained/pm-cli/sdk";
+```
+
+`PM_COMMAND_ALIAS_CONTRACTS` carries `alias`, `canonical`, `canonical_argv`, `lifecycle`, `hidden`, `registration`, and `owner`. `verifyPmCliGrammar` returns deterministic findings with an offending spelling and nearest conforming target.
+
+Runtime contracts expose the compact noun/verb policy in summary output and include the exhaustive destination census in full output. Deprecated aliases remain queryable but are excluded from the default command-summary denominator.
+
+## Compatibility and Migration Hints
+
+Hints go to stderr exactly once per deprecated-alias invocation and never alter stdout. Disable them for a project when an automation intentionally retains old spellings:
+
+```bash
+pm config project set ux_deprecation_hints false
+```
+
+This setting changes presentation only. It does not disable aliases or change command results. The uniform machine result-envelope receipt is intentionally deferred to its separately tracked cross-command contract so this implementation does not create a list-only shape.
+
+## Enforcement
+
+`pnpm quality:command-grammar` builds the SDK, reads the live runtime command contracts, and compares them with the checked-in destination and alias tables. Package-owned destination rows are conditional because installed packages vary by workspace; every activated package command still requires a declared row, while an inactive package does not make its row stale. The gate also proves parity between discoverable SDK actions, the MCP `pm_run` action enum, and narrow MCP tools. The same gate runs inside `quality:static`, alongside contract drift checks. Its negative controls prove that unknown commands, stale core rows, broken alias targets, MCP drift, and surface-ceiling growth fail upward.
+
+## Consequences
+
+- Agents discover one list command instead of eight repeated help pages.
+- Existing scripts keep working and receive an actionable replacement.
+- CLI, SDK, completion, and contract consumers share one alias table.
+- New commands require an explicit architectural home and PM owner.
+- The compatibility table is long-lived public API and must be reviewed like any other SDK contract.
+- Consolidation proceeds incrementally: current legacy commands may remain only with a named disposition until their owning PM item lands.

package/docs/COMMANDS.md

@@ -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

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/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/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,9 @@ 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).
 
 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 +202,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 +296,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`
@@ -1468,6 +1472,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 +1584,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/agent-task-token-baseline.json

@@ -6,20 +6,20 @@
   "scenarios": [
     {
       "id": "small-workspace",
-      "max_estimated_tokens": 626
+      "max_estimated_tokens": 552
     },
     {
       "id": "large-workspace",
-      "max_estimated_tokens": 1231
+      "max_estimated_tokens": 1055
     },
     {
       "id": "returning-agent",
-      "max_estimated_tokens": 597
+      "max_estimated_tokens": 371
     },
     {
       "id": "failing-command",
-      "max_estimated_tokens": 197
+      "max_estimated_tokens": 200
     }
   ],
-  "composite_max_estimated_tokens": 2651
+  "composite_max_estimated_tokens": 2178
 }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.17",
+  "version": "2026.8.18",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,8 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
+    "quality:static": "pnpm build && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
+    "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
     "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",