@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/docs/SDK.md

@@ -42,6 +42,14 @@ semantic command discovery, and append-stable linked tests are tracked by
 [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon),
 [pm-g543](../.agents/pm/issues/pm-g543.toon), and
 [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon).
+The supported CLI entrypoint boundary, truthful context-intent receipts, and
+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.
 
@@ -90,8 +98,14 @@ barrel remains source-compatible:
 | `@unbrained/pm-cli/sdk/public-surface.json` | Published machine-readable SDK compatibility snapshot                      |
 | `@unbrained/pm-cli/sdk`                     | Compatibility aggregate containing every supported SDK export              |
 
-`@unbrained/pm-cli/cli` remains the runtime CLI module entrypoint for package
-resolution, not a typed library API. The committed
+`@unbrained/pm-cli/cli` is the supported embeddable CLI entrypoint and exports
+only `runPmCli`. Repository tests import their internal seams from source; those
+helpers are not package API. The surface snapshot records the subpath under the
+`executable_entry` classification, so any future exposure is a classified
+surface change. The bare
+`@unbrained/pm-cli` root export is recorded as an `aggregate_alias` of
+`@unbrained/pm-cli/sdk`: its symbols are not duplicated, but a retarget of its
+declaration path is a snapshot change. The committed
 [entrypoint import-cost table](performance/sdk-entrypoint-import-costs.md)
 records fresh-process latency, RSS, and reduction versus the aggregate barrel.
 Every narrow entrypoint is bundled and type-tested independently.
@@ -137,6 +151,12 @@ from every non-testing SDK subpath must be available from
 Consumers and release tooling can read the exact shipped artifact from
 `@unbrained/pm-cli/sdk/public-surface.json` without locating repository files.
 
+The denominator is the package export map itself, not a list inside the
+generator. Every `exports` entry that declares a `types` path must carry a
+classification, and `pnpm sdk:surface:check` refuses to run while any published
+code export is unclassified — so adding a public entrypoint cannot ship it
+ungoverned.
+
 ## Public Exports
 
 Source of truth:
@@ -182,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)
@@ -275,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`
@@ -301,6 +322,7 @@ Command/action contract exports:
 - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
 - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
 - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
+- Built-in `recurs_from` records that the source is a later occurrence of the target. Its registry contract is directed, `source_after_target`, non-ordering, many-to-many, and persistent across terminal lifecycle states. Local mutation paths enforce strictly later source `created_at` metadata before item or history persistence and return structured source/target evidence when chronology is equal, reversed, or unverifiable. It therefore connects an incident family for traversal and analytics without reclassifying `supersedes` replacements or `duplicate_of` identity collapse.
 - Atomic application transactions: `commitWorkspaceTransaction` coordinates ordered, idempotent item and relationship mutations under one workspace writer lock and a durable replay journal. Interrupted work resumes from step inspection; ordinary failures append reverse-order compensations without rewriting immutable histories.
 - Multi-branch merge primitives: `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, and `runMergeReconcile` provide the same field-aware item, hash-chain-preserving history, sequence-renumbering relationship-event, key-level configuration, and audited post-merge repair-and-verify semantics as `pm merge`; `installMergeFence` and `findGitWorkspaceRoot` let custom init hosts install the same contract with explicit roots, while `buildMergeAttributePatterns`, `refreshMergeAttributeFenceIfInstalled`, and `auditMergeAttributeFence` expose fence coverage, refresh, and validation. See [Multi-Branch Merge Safety](MERGE_SAFETY.md).
 - Dependency provenance primitives: `EXTERNAL_DEPENDENCY_SOURCE_KIND`, `EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS`, `isExternalDependencySourceKind`, and `normalizeDependencySeedId` let custom importers preserve cross-workspace dependency ids explicitly while retaining local prefix normalization for ordinary seeds. `source_kind: "external"` is the human-facing alias and persists canonically as `global`; a `blocked_by` row with that provenance is a real external predecessor, so graph governance does not require a fabricated local item or misreport `stale_lifecycle_block`. Newly created dependency rows also carry the effective `author`, `author_source` (`asserted` or `detected`), and a mutation `source_kind`; legacy rows remain readable without invented provenance. Tracked by [pm-6sc8jq](../.agents/pm/issues/pm-6sc8jq.toon).
@@ -348,9 +370,10 @@ rendering stay at the edge.
 Embedded hosts can also import the SDK-owned bootstrap normalization primitives
 (`normalizeBootstrapInvocation`, `parseBootstrapGlobalOptions`, and related
 contracts) when they intentionally expose pm-compatible argv. Every
-`runPmCli()` call constructs a fresh Commander graph, so extension commands,
-extension flags, and runtime schema options from one workspace cannot leak into
-the next in-process invocation.
+`runPmCli()` call constructs a fresh Commander graph and restores the host's
+existing `process.exitCode` after both successful and failed invocations, so
+extension state and CLI exit state from one workspace cannot leak into the next
+in-process invocation.
 
 ### Build a non-PM temporal domain
 
@@ -653,6 +676,20 @@ representative medium-workspace answers use the live
 negative control: the gate fails unless that deliberately unsafe request
 exceeds the default contract.
 
+Named read intents additionally return `context_intent`. The receipt separates
+the declaration (`declared_token_budget`) from the effective ceiling
+(`token_budget`) and reports their signed `token_budget_override`. Row-oriented
+reads clamp an explicit limit to the budget-derived ceiling and identify the
+binding constraint. `declaration_feasible` evaluates the useful projection
+against the declared ceiling independently of whether a lower or higher caller
+override is effective. `within_budget` evaluates that same projection against
+the effective `token_budget`, so it can legitimately differ from declaration
+feasibility. If even compacted useful output cannot fit,
+`result_omitted` is true, `estimated_tokens` retains the measured pre-omission
+size (and is therefore greater than `token_budget`), and
+`budget_exceeded.restore_with` is an executable bounded retry rather than a
+generic suggestion.
+
 Unfiltered `pm contracts` now selects the summary projection by default. It
 returns canonical commands, terse intents, the most useful flags for the core
 agent loop, per-command ceilings, and the shared output policy. Use
@@ -1435,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`,
@@ -1543,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/SDK_RUNTIME_BOUNDARIES.md

@@ -45,9 +45,17 @@ the stable, path-redacted `host_environment_capacity_fault`,
 `host_environment_permission_fault`, or `host_environment_resource_fault`
 contracts. `classifyHostEnvironmentFault` supports diagnostics that need a
 non-throwing classification, while `translateHostEnvironmentFault` supports an
-existing catch boundary. Non-errno failures are returned unchanged and must
+existing catch boundary. The classifier accepts both symbolic Node `code`
+values and declared numeric `errno` values from `node:os.constants.errno`; this
+also recognizes platform errors that Node renders only as a number, such as a
+Linux `-122` quota failure. Non-errno failures are returned unchanged and must
 not be relabeled as environment faults.
 
+Linked-test tracker seeding uses this boundary. A required sandbox copy that
+exceeds temporary-filesystem capacity fails with a stable recovery contract,
+while linked tests whose effective context is schema avoid materializing
+tracker data at all.
+
 Existing SDK surfaces can supply category-specific `codes` to preserve their
 published error vocabulary while still sharing classification, path redaction,
 and recovery guidance. Workspace snapshots use this compatibility path for

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).
+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).
 
 ## Agent Quick Context
 
@@ -353,6 +353,13 @@ The manifest records baseline bytes and estimated tokens for visible review
 deltas. Updating it cannot raise answer ceilings, which remain owned by
 `PM_COMMAND_OUTPUT_BUDGET_CONTRACTS`.
 
+The gate derives every supported harness, model, session, and provenance
+environment key from the SDK-owned harness descriptor registry. It deletes
+those host inputs before each fixture invocation, then supplies only the
+fixture's deterministic author and isolated tracker settings. Unrelated host
+environment values remain available, so the test process stays representative
+without allowing the launching agent or CI harness to change measured output.
+
 ## Linked Tests
 
 Add tests to the item that owns the work:
@@ -399,6 +406,16 @@ When a linked command is a PM tracker-read such as `pm validate`, the default mi
 `--auto-pm-context`, which keeps schema isolation for ordinary commands and routes only tracker-read PM commands
 through seeded tracker data.
 
+The runner resolves every selected command's effective context before it
+creates temporary sandboxes. Runs whose effective context is schema initialize
+only their schema roots; a non-PM command explicitly configured with
+`pm_context_mode: "tracker"` still requires tracker data. Tracker roots and item
+data are materialized only when at least one selected command requires tracker
+context. This preserves source isolation without copying an unrelated tracker
+into constrained temporary storage.
+Capacity, permission, and resource failures while seeding a required tracker
+surface as typed, path-redacted host-environment refusals with recovery steps.
+
 Use explicit modes when needed:
 
 ```bash

package/docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md

@@ -61,7 +61,7 @@ Each measurement result carries `definition_fingerprint`; assertion verdicts cop
 }
 ```
 
-The semantic numerator is the sum of `discovered_from`, `incident_from`, `supersedes`, and `verifies`. Audit baselines preserve the new fields, accept older snapshots with explicit zero defaults, and report signed count/share deltas.
+The semantic numerator is the sum of `discovered_from`, `incident_from`, `recurs_from`, `supersedes`, and `verifies`. Audit baselines preserve the new fields, accept older snapshots with explicit zero defaults, and report signed count/share deltas.
 
 ## Health Row Predicate
 

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.16"
+    "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.16",
+      "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.16",
+  "version": "2026.8.18",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -77,9 +77,9 @@
     },
     "./sdk/public-surface.json": "./sdk/public-surface.json",
     "./cli": {
-      "types": "./dist/cli/main.d.ts",
-      "import": "./dist/cli/main.js",
-      "default": "./dist/cli/main.js"
+      "types": "./dist/cli/public.d.ts",
+      "import": "./dist/cli/public.js",
+      "default": "./dist/cli/public.js"
     },
     "./package.json": "./package.json"
   },
@@ -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",
@@ -136,6 +137,7 @@
     "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
     "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
+    "quality:defect-evidence": "pnpm build && node scripts/release/defect-evidence-gate.mjs",
     "quality:hosted-analysis": "node scripts/release/hosted-analysis-gate.mjs",
     "benchmark:scale:generate": "node scripts/bench/scale-workspace.mjs",
     "benchmark:scale": "node scripts/bench/run-scale-benchmarks.mjs",
@@ -145,6 +147,7 @@
     "benchmark:sdk-entrypoints:check": "pnpm build && node scripts/bench/sdk-entrypoint-costs.mjs --check",
     "benchmark:transport:update": "pnpm build && node scripts/bench/cli-transport-floor.mjs --update",
     "benchmark:transport:check": "pnpm build && node scripts/bench/cli-transport-floor.mjs --check",
+    "benchmark:defect-recurrence": "pnpm build && node scripts/bench/defect-recurrence-index.mjs --check",
     "contracts:update": "node scripts/contracts-snapshot.mjs --update",
     "contracts:check": "pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check",
     "contracts:errors:update": "node scripts/generate-error-code-catalog.mjs",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "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.8.16",
+  "version": "2026.8.18",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"