@unbrained/pm-cli 2026.8.13 → 2026.8.14

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,17 +1,17 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), and [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), and [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon).
 
 ## Agent Quick Context
 
 Every built-in read surface uses four output dimensions: what to include, how much to return, how much the result may cost, and how to encode it. The same canonical controls work through the CLI, SDK, MCP, generated schemas, runtime contracts, and shell completions.
 
-| Dimension | CLI                             | SDK and MCP     | Meaning                                                    |
-| --------- | ------------------------------- | --------------- | ---------------------------------------------------------- |
-| Include   | `--output-include <csv>`        | `outputInclude` | Retain named fields or top-level sections.                 |
-| Amount    | `--output-limit <n\|unbounded>` | `outputLimit`   | Bound shared row collections.                              |
-| Cost      | `--output-budget <tokens>`      | `outputBudget`  | Fail closed when even the compact result cannot fit.       |
-| Encoding  | `--output-format <toon\|json>`  | `outputFormat`  | Select the CLI renderer and record the requested encoding. |
+| Dimension | CLI                             | SDK and MCP     | Meaning                                                                |
+| --------- | ------------------------------- | --------------- | ---------------------------------------------------------------------- |
+| Include   | `--output-include <csv>`        | `outputInclude` | Retain named fields or sections, or select a declared projection mode. |
+| Amount    | `--output-limit <n\|unbounded>` | `outputLimit`   | Bound shared row collections.                                          |
+| Cost      | `--output-budget <tokens>`      | `outputBudget`  | Fail closed when even the compact result cannot fit.                   |
+| Encoding  | `--output-format <toon\|json>`  | `outputFormat`  | Select the CLI renderer and record the requested encoding.             |
 
 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`.
 
@@ -24,6 +24,39 @@ repeated metadata from results by default. Request
 `--output-row-contract` / `outputRowContract: true` when a consumer needs the
 row paths, jq selector, and active TOON encoding contract.
 
+### Include Modes
+
+`--output-include` accepts two kinds of token. A **field selector** names a row
+field or section and narrows the computed result. A **projection mode** names a
+whole declared projection and is the canonical spelling of a command-local mode
+flag: `brief`, `compact`, `full`, `summary`, and `counts`, depending on the
+surface. Controls that change execution rather than projection remain separate:
+for example, `deps --collapse <none|repeated>` retains dependency-grouping
+semantics, and `health --check-only` retains refresh-suppression semantics.
+
+Mode tokens are resolved before the command computes its rows, because a mode
+selects which fields exist rather than which of the computed fields survive.
+`pm list --output-include brief` is therefore exactly `pm list --brief`, and the
+two are byte-identical apart from the `read_output` receipt that records which
+spelling was used. Modes and field selectors compose: the mode selects the
+projection, the remaining selectors narrow it.
+
+```bash
+pm list --status open --output-include brief          # same result as --brief
+pm contracts --output-include full                    # same result as --full
+pm list --status open --output-include brief,id       # brief projection, id only
+```
+
+Read `readOutputIncludeModeOptions(command)` from the SDK for the exact
+replacement modes a surface declares. Every compatibility alias also declares
+`semantics: "replacement" | "behavior_preserving"`; generators therefore do
+not have to infer obligation strength from prose. The executable migration test
+derives all 22 projection-mode replacements from this table, invokes both
+spellings in a temporary tracker, and compares their useful result after
+removing spelling receipts and volatile run metadata. A selector that matches
+neither a declared mode nor any field on any returned row is refused with the
+legal domain, rather than returning rows with every field removed.
+
 ## Cross-Call Context Sessions
 
 `--output-session <json>` / `outputSession` composes the four per-call
@@ -92,7 +125,9 @@ pm stats --output-row-contract
 pm contracts --full --json
 ```
 
-Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
+
+When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and an executable recovery instruction — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result and reports `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
 
 ## SDK and Package Usage
 
@@ -127,5 +162,6 @@ The full runtime contract reports every surface and all four dimensions. Strict
 ```bash
 pnpm contracts:check
 node scripts/run-tests.mjs test -- tests/unit/sdk/read-output-contracts.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/sdk/read-output-migration-hints.spec.ts
 node scripts/run-tests.mjs test -- tests/unit/commands/completion-command.spec.ts
 ```

package/docs/RELATIONSHIP_GRAPH.md

@@ -1,6 +1,6 @@
 # Relationship graph semantics
 
-Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), and [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon).
+Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), and [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon).
 
 ## Decision
 
@@ -251,14 +251,21 @@ terminal dangling-reference partitions. Domain adapters pass their
 company, or package-defined edges survive assembly with their registered
 semantics. `auditWorkspaceRelationshipGraph`
 consumes that assembly and emits counts-first findings for active/terminal
-missing references, retired sentinels, ordering cycles, stale lifecycle blocks,
-and sparse or isolated active nodes. Findings include stable codes, severity,
+missing references, retired sentinels, ordering cycles, exact
+scalar-versus-structured ordering contradictions, stale lifecycle blocks, and
+sparse or isolated active nodes. Findings include stable codes, severity,
 bounded deterministic samples, truncation, policy text, and safe remediation;
 the audit never invents an edge. Explicit isolate exemptions suppress policy
 findings without changing structural coverage metrics.
 
 The audit profile also exposes graph-wide resilience and delivery-lineage
-metrics. `articulation_points` and `bridge_edges` reuse the exact cut-structure
+metrics. `nodes` and `edges` remain diagnostic totals. Structural ratchets use
+`recorded_nodes`, which excludes synthesized missing/external placeholders,
+and `informative_edges`, which subtracts the union of witnessed redundant edge
+identities and structured rows proven to contradict scalar blocker precedence.
+`redundant_edges` and `ordering_contradiction_edges` remain separate debt
+censuses so repair can tighten their ceilings without weakening the
+information-bearing floor. `articulation_points` and `bridge_edges` reuse the exact cut-structure
 algorithm; outcome metrics count explicit `Milestone` titles beginning with
 `Outcome milestone:` and follow only hierarchy or `implements` edges toward
 them. Active and terminal populations are reported separately, with integer
@@ -340,7 +347,15 @@ on terminal ones) reports raw dependency rows whose exact identity is stored
 more than once on one holder — invisible to every assembled-graph projection
 because graph construction deduplicates edges by identity, so
 `collectDuplicateDependencyRows` scans the pre-assembly item rows carried on
-the assembly. Coverage policy is type-aware: the audit profile's
+the assembly. `collectOrderingStorageContradictions` similarly scans raw rows
+before normalization: `blocked_by: target` plus a same-target source-first
+ordering dependency asserts both directions and manufactures a two-node cycle.
+The audit reports the exact holder, target, and removable dependency kind under
+`ordering_storage_contradiction` or
+`legacy_ordering_storage_contradiction`; cycle findings attach that evidence
+instead of leaving agents to re-derive the storage cause. Mutation advisories
+also identify a newly introduced contradiction before reporting its derived
+cycle. Coverage policy is type-aware: the audit profile's
 `coverage_by_type` breaks active/isolated/degree≤1 counts down per item type
 (untyped items under `(untyped)`), and `isolateExemptTypes`
 (`--exempt-isolate-type`) suppresses isolate/sparse findings for types whose

package/docs/SDK.md

@@ -284,7 +284,7 @@ Command/action contract exports:
 - Large-workspace memory primitives: `buildWorkspaceMemorySnapshot`, `readWorkspaceMemory`, `selectWorkspaceMemoryRollups`, and `searchWorkspaceMemory` build cursor-bound, rebuildable calendar-epoch and epic-lineage summaries. The stock `context` and `search` results attach matching bounded rollups automatically at 10,000 items; smaller projects skip the artifact entirely.
 - Persistent metadata-query primitives: `queryItemMetadataIndex` with `ItemMetadataIndexQuery` / `ItemMetadataIndexQueryResult` executes bounded status/type/id/parent/assignee/sprint/release/priority windows without materializing the JSON metadata corpus. It returns `null` on absent, stale, or corrupt derived state so custom hosts can fall back to authoritative reads.
 - Schema-evolution primitives: `planSchemaEvolutionMigration` and `runSchemaEvolutionMigration`, plus `PmClient.schemaRenameType`, `schemaRenameField`, and `schemaRemapStatus`, provide deterministic dry-run plans, collision refusal, index-backed candidate selection, per-item immutable history, and crash-resumable workspace transactions.
-- Workspace audit primitives: `appendWorkspaceHistoryChange`, `writeWorkspaceJsonWithHistory`, `getWorkspaceHistoryPath`, and `WORKSPACE_HISTORY_ID` let package-owned singleton JSON mutations share the CLI's verified `HistoryEntry` stream instead of inventing an unaudited side log.
+- Workspace audit primitives: `appendWorkspaceHistoryChange`, `writeWorkspaceJsonWithHistory`, `inspectWorkspaceHistoryState`, `reconcileWorkspaceJsonHistory`, `restoreWorkspaceJsonFromHistory`, `getWorkspaceHistoryPath`, and `WORKSPACE_HISTORY_ID` let package-owned singleton JSON mutations share the CLI's verified `HistoryEntry` stream, prove replay-to-disk agreement, and recover forward without inventing an unaudited side log or rewriting history.
 - Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, `graph`, and `append`
 - Workspace graph-query runner: `runGraph` (with `GraphCommandOptions`, `GraphResult`, and per-subcommand envelopes) resolves the workspace relationship graph through the shared fingerprint-keyed cache and dispatches bounded `ancestors`/`descendants`/`predecessors`/`successors`/`paths`/`impact`/`analyze`/`audit`/`communities`/`redundancy`/`dominators`/`slack`/`centrality`/`articulation`/`plan` queries with counts-first cost, truncation, and cache metadata; the `pm graph` CLI command and `pm_graph` MCP tool are thin adapters over it.
 - Structural graph analytics: `detectRelationshipCommunities` (deterministic label-propagation clustering with `maxIterations`/`minSize` bounds and convergence reporting), `findRedundantRelationshipEdges` (transitive-reduction scan that joins each directed ordering or hierarchy kind with its inverse spelling and returns witness paths), and `computeRelationshipDominators` (Cooper–Harvey–Kennedy immediate dominators with per-node gating weights for bottleneck ranking) — all deterministic, cancellable, and cost-metered like every other graph query.
@@ -292,8 +292,8 @@ Command/action contract exports:
 - Incremental graph cache: `WorkspaceGraphCache`, `workspaceGraphCache`, `resetWorkspaceGraphCache`, and `computeWorkspaceGraphFingerprint` reuse the assembled workspace graph and memoize deterministic query results under a fingerprint that digests every relationship-relevant item field (id, title, status and terminal classification, item type, parent, legacy blocker, structured dependencies), so long-lived hosts stop paying full-workspace assembly per bounded query; `GraphCacheMetadata` reports assembly/result hit-or-miss on every `runGraph` envelope.
 - Durable graph index: `openDurableGraphCache`, `persistDurableGraphResult`, `clearDurableGraphCache`, `durableGraphCacheStatus`, `shouldPersistDurableGraphCache`, and the `durableGraphCachePath`/`graphAuditBaselinePath` locators persist fingerprint-keyed deterministic query results across processes under `runtime/graph-cache.json` — atomic writes, corrupt-tolerant decode, bounded retention, never authoritative (rebuildable from item storage), optional below the `GRAPH_DURABLE_CACHE_MIN_ITEMS` threshold; `pm graph index` is the maintenance surface and `cache.durable` the per-envelope observability.
 - Temporal audit census: `RelationshipAuditSnapshot`, `diffRelationshipAuditSnapshots`, `saveGraphAuditBaseline`, and `loadGraphAuditBaseline` persist and compare point-in-time governance censuses (signed per-code and per-profile deltas, `same_snapshot` fingerprint equality) behind `pm graph audit --save-baseline` and the automatic `baseline` drift block on later audits.
-- Storage-integrity and coverage governance: `collectDuplicateDependencyRows` reports raw same-identity dependency rows duplicated on one holder (the `duplicate_dependency_row`/`legacy_duplicate_dependency_row` audit families; invisible to assembled-graph projections), `RelationshipCoverageProfile.coverage_by_type` breaks active connectivity down per item type, and `RelationshipAuditOptions.isolateExemptTypes` suppresses coverage findings for policy-valid disconnected types.
-- Incremental mutation advisory: `collectNewOrderingCycleWarnings` detects newly created ordering cycles component-scoped around the changed item over a lightweight per-snapshot ordering digraph (shared `collectOrderingCycles` Tarjan semantics with the audit; no full workspace assembly per mutation), and `resolveWorkspaceRelationshipKindRegistry` exposes the built-in-plus-extension relationship-kind registry resolution every surface shares.
+- Storage-integrity and coverage governance: `collectDuplicateDependencyRows` reports raw same-identity dependency rows duplicated on one holder; `collectOrderingStorageContradictions` reports exact scalar blocker plus opposite-precedence structured rows before graph normalization; `RelationshipCoverageProfile` separates diagnostic `nodes`/`edges` from invariant-bearing `recorded_nodes`/`informative_edges` and independent redundancy/contradiction debt counts; `coverage_by_type` breaks active connectivity down per item type, and `RelationshipAuditOptions.isolateExemptTypes` suppresses coverage findings for policy-valid disconnected types.
+- Incremental mutation advisory: `collectNewOrderingCycleWarnings` detects newly created ordering cycles component-scoped around the changed item over a lightweight per-snapshot ordering digraph and emits exact newly stored scalar-versus-structured contradiction evidence before the derived cycle warning (shared registry and `collectOrderingCycles` Tarjan semantics with the audit; no full workspace assembly per mutation).
 - Remediation planning: `planRelationshipRemediation` (with `RelationshipRemediationPlan`, `RelationshipRemediationStep`, and operation/confidence/code contracts) derives exact dry-run `remove`/`retype`/`supersede`/`waive`/`investigate` proposals from governance-audit findings and witnessed redundancy rows — evidence-backed, confidence-rated, and never auto-applied.
 - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
 - Annotation kernel primitives: `resolveAnnotationInput`, `runAnnotationCommand`, `resolveAnnotationIndex`, `parseAnnotationTextInput`, `limitAnnotationEntries`, `readAnnotationEntries`, `wrapOwnershipConflict`, `isErrnoError`, and their typed input/config/result contracts
@@ -1167,10 +1167,17 @@ snapshot, atomic write, history append, and any compensating restore, so
 competing SDK writers cannot split persisted state from its audit chain. The
 stream participates in the history merge driver, appears in `pm activity`, and
 can be checked with
-`pm history _workspace --verify`. Package authors that persist their own
+`pm history _workspace --verify`. Verification also replays the latest document
+map and compares every governed JSON singleton with disk; a valid chain is not
+reported healthy when the live document differs. Package authors that persist their own
 singleton JSON should call `writeWorkspaceJsonWithHistory`; use
 `appendWorkspaceHistoryChange` only when another primitive already owns the
-document write.
+document write. Recovery code uses `inspectWorkspaceHistoryState` for the
+read-only classification, `reconcileWorkspaceJsonHistory` only when a terminal
+Decision explicitly authorizes adoption of the reviewed disk value, and
+`restoreWorkspaceJsonFromHistory` to reject drift and replace the singleton
+from a verified version. Reconciliation and restoration append new entries and
+compensate failed writes; neither edits historical rows.
 
 ```ts
 import {

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), and [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), and [pm-5t33or](../.agents/pm/features/pm-5t33or.toon).
 
 ## Agent Quick Context
 
@@ -31,6 +31,31 @@ selector grammar and omission receipts as any other SDK-owned item field.
 
 The same SDK-owned read-output registry now declares `package manage` as a first-class read surface. Package authors can resolve either `package manage` or `package-manage` to its canonical contract and discover the universal include, amount, cost, and encoding dimensions without copying CLI knowledge.
 
+Compatibility aliases declare whether their migration promise is an exact
+`replacement` or only `behavior_preserving`. Exact projection modes are
+available through `readOutputIncludeModeOptions()` and are executed against
+their legacy spelling in the temporary-tracker contract suite. Execution
+controls such as `deps --collapse <value>` and `health --check-only` retain
+their independent semantics and are never exposed as false include-mode
+replacements.
+
+Every registered read surface also resolves a format-aware default token ceiling
+from the public command-output contract. Results already inside that ceiling are
+returned byte-for-byte unchanged, so the safety default adds no receipt overhead
+to ordinary reads. Oversized results follow the shared compaction ladder and
+identify `budget_source: default` plus the applied `budget_tokens` in their
+`read_output` receipt. Complete internal artifacts and callers that intentionally
+accept unbounded output must say so explicitly with `--output-budget unbounded`
+or `outputBudget: "unbounded"`; that opt-out is distinct from row-count
+`--unbounded` compatibility behavior.
+
+The budget ladder separately discovers nested arrays below declared result
+rows. This lets governance envelopes reduce diagnostic findings before
+omitting the whole verdict without redefining a nested tag or remediation list
+as a pagination row. Receipts name every `compacted_row_paths` entry; a complete
+omission also records the useful result's pre-omission estimate, while the
+universal recovery remains `--output-budget unbounded`.
+
 ## Row discovery and exact output receipts
 
 Row locations and encoding capabilities remain part of the SDK-owned read
@@ -85,6 +110,12 @@ The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAu
 
 Storage integrity is evaluated independently of that provider boundary. Lossless merge receipts remain visible as provenance, while only receipts containing discarded scalar values produce `merge_decisions_unreviewed` guidance; neither classification enables vector refresh or remote provider I/O.
 
+Default history-drift verification also replays the append-only `_workspace`
+stream and compares every governed singleton with its latest recorded state.
+That agreement check reads only local history and JSON files: mismatched,
+missing, or unreadable singleton paths become bounded `history_drift` evidence
+without enabling embeddings, vector-store access, or any other provider I/O.
+
 Brief and summary check-only health projections use the scalar-only metadata
 reader. Validation uses collection-bearing metadata for evidence and
 relationship checks and materializes bodies only when strict history-drift

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).
+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).
 
 ## Agent Quick Context
 
@@ -100,6 +100,28 @@ node scripts/run-tests.mjs test -- tests/integration/cli.integration.spec.ts
 
 Use focused runs while iterating, then run coverage before closure when risk or scope warrants it.
 
+## CI Retry and Timeout Diagnostics
+
+CI retains the 30-second per-test timeout and retries one failed attempt. A
+test that passes only on retry is reported as flaky rather than silently folded
+into the pass count; a persistent assertion still fails after the bounded
+retry. Local runs do not retry, so deterministic failures stay immediate while
+iterating.
+
+Vitest's GitHub reporter emits annotations and retry evidence. The repository
+reliability reporter additionally writes
+`.vitest-reports/reliability-<shard>.json` and appends a job-summary table with
+the test identity, file, duration, effective timeout, retry count, shard, and
+failure detail. Tests completing at or above 80% of their timeout are recorded
+as at-risk before load turns them into timeouts. Coverage shards upload this
+JSON beside their blob report, so recurrence can be measured without decoding
+the coverage artifact or re-reading raw logs.
+
+`PM_TEST_SHARD` supplies a stable shard identity and
+`PM_TEST_RELIABILITY_REPORT_DIR` can redirect the JSON report for an isolated
+harness. These variables affect diagnostics only; they do not change test
+selection, retry count, timeout, or verdicts.
+
 ## Coverage Governance
 
 Coverage gating now targets literal all-source coverage across runtime code families:

package/docs/performance/sdk-entrypoint-import-costs.md

@@ -1,7 +1,9 @@
 # SDK entrypoint import costs
 
 Tracked by [pm-38bskj](../../.agents/pm/tasks/pm-38bskj.toon) and
-[pm-cg1sjb](../../.agents/pm/issues/pm-cg1sjb.toon).
+[pm-cg1sjb](../../.agents/pm/issues/pm-cg1sjb.toon). Standalone merge-bundle
+topology is tracked by
+[pm-m9gu9r](../../.agents/pm/chores/pm-m9gu9r.toon).
 
 This table measures fresh-process ESM import and module evaluation. The bare
 Node v26.5.0 process floor on linux/x64
@@ -13,20 +15,25 @@ against the unchanged upper-bound budget and 30 ms scheduler margin. A single
 cold or descheduled process therefore cannot fail the gate, while a majority of
 over-budget samples still does; p95 remains visible as diagnostic evidence.
 
-| Package export | p50 | p95 | p50 above Node | Reduction vs aggregate |
-|---|---:|---:|---:|---:|
-| `./sdk` | 248 ms | 249 ms | 207 ms | 0% |
-| `./sdk/authoring` | 71 ms | 76 ms | 30 ms | 85.5% |
-| `./sdk/contracts` | 73 ms | 87 ms | 32 ms | 84.5% |
-| `./sdk/core` | 221 ms | 255 ms | 180 ms | 13% |
-| `./sdk/governance` | 154 ms | 161 ms | 113 ms | 45.4% |
-| `./sdk/graph` | 87 ms | 87 ms | 46 ms | 77.8% |
-| `./sdk/merge` | 111 ms | 122 ms | 70 ms | 66.2% |
-| `./sdk/query` | 100 ms | 105 ms | 59 ms | 71.5% |
-| `./sdk/runtime` | 251 ms | 289 ms | 210 ms | -1.4% |
-| `./sdk/testing` | 241 ms | 307 ms | 200 ms | 3.4% |
+| Package export     |    p50 |    p95 | p50 above Node | Reduction vs aggregate |
+| ------------------ | -----: | -----: | -------------: | ---------------------: |
+| `./sdk`            | 248 ms | 249 ms |         207 ms |                     0% |
+| `./sdk/authoring`  |  71 ms |  76 ms |          30 ms |                  85.5% |
+| `./sdk/contracts`  |  73 ms |  87 ms |          32 ms |                  84.5% |
+| `./sdk/core`       | 221 ms | 255 ms |         180 ms |                    13% |
+| `./sdk/governance` | 154 ms | 161 ms |         113 ms |                  45.4% |
+| `./sdk/graph`      |  87 ms |  87 ms |          46 ms |                  77.8% |
+| `./sdk/merge`      | 111 ms | 122 ms |          70 ms |                  66.2% |
+| `./sdk/query`      | 100 ms | 105 ms |          59 ms |                  71.5% |
+| `./sdk/runtime`    | 251 ms | 289 ms |         210 ms |                  -1.4% |
+| `./sdk/testing`    | 241 ms | 307 ms |         200 ms |                   3.4% |
 
 The aggregate `@unbrained/pm-cli/sdk` remains supported for compatibility.
 New packages should import the narrowest subpath that owns their capability.
+The build emits `./sdk/merge` as a standalone no-splitting bundle because its
+dependency closure overlaps with several broader focused entrypoints. Keeping
+that surface in the shared focused chunk graph made a merge-only import traverse
+unrelated chunks; the isolated output preserves the same public exports while
+keeping its runtime loading cost proportional to the capability requested.
 The committed budget file is an upper-bound ratchet and must not be weakened to
 hide a regression.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.13",
+  "version": "2026.8.14",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
     "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 && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && 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/absence-tolerance-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json && 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 && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 113 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && 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/absence-tolerance-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-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: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",
@@ -130,7 +130,7 @@
     "quality:retrieval-eval": "pnpm build && node scripts/release/retrieval-eval-gate.mjs",
     "quality:retrieval-eval:update": "pnpm build && node scripts/release/retrieval-eval-gate.mjs --update",
     "quality:gate-registry": "pnpm build && node scripts/release/gate-registry.mjs",
-    "quality:tracker-measurements": "pnpm build && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json",
+    "quality:tracker-measurements": "pnpm build && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded",
     "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
     "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
     "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
@@ -219,11 +219,11 @@
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",
-    "greptile": "^3.3.1",
-    "jscpd": "^5.0.14",
+    "greptile": "^3.4.0",
+    "jscpd": "^5.0.15",
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.66.0",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"
   }

package/packages/pm-beads/extensions/beads/index.ts

@@ -58,6 +58,7 @@ export function activate(api: ExtensionApi): void {
     {
       action: "beads-import",
       description: "Import Beads JSONL records into pm items.",
+      intent: "Import Beads records through audited pm item mutations.",
       failure_hints: [
         "Use the host-global --author <id> flag when an explicit mutation identity override is required.",
       ],

package/packages/pm-beads/package.json

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

package/packages/pm-calendar/extensions/calendar/index.ts

@@ -217,6 +217,7 @@ function calendarCommand(name: "calendar" | "cal"): CommandDefinition {
     name,
     action: "calendar",
     description: "Show deadline, reminder, and scheduled event calendar views.",
+    intent: "Inspect time-bounded project context across schedules and work.",
     arguments: [
       {
         name: "view",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.13",
+  "version": "2026.8.14",
   "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.13",
+  "version": "2026.8.14",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/extensions/digital-twin/index.ts

@@ -697,6 +697,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-entity-create",
       description:
         "Create a stable facility or asset identity and its first immutable state event.",
+      intent: "Create one digital-twin entity with an attributable initial state.",
       arguments: ENTITY_ARGUMENT,
       flags: [
         { long: "--title", value_name: "text", value_type: "string" },
@@ -728,6 +729,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-observe",
       description:
         "Append an attributable observation or correction with optimistic concurrency.",
+      intent: "Append a versioned observation to one digital-twin entity.",
       arguments: ENTITY_ARGUMENT,
       flags: [
         {
@@ -756,6 +758,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-relate",
       description:
         "Append or supersede one typed containment, flow, or utility relationship.",
+      intent: "Record one typed relationship in the digital-twin topology.",
       arguments: ENTITY_ARGUMENT,
       flags: [
         {
@@ -789,6 +792,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-query",
       description:
         "Query point-in-time state, topology, provenance, conflicts, invariants, and impact.",
+      intent: "Inspect one entity's point-in-time state and topology impact.",
       arguments: ENTITY_ARGUMENT,
       flags: [
         { long: "--at", value_name: "iso", value_type: "string" },
@@ -802,6 +806,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-export",
       description:
         "Export a bounded shell-friendly event bundle with a tamper-evident checkpoint.",
+      intent: "Export a bounded portable digital-twin event bundle.",
       flags: [
         { long: "--at", value_name: "iso", value_type: "string" },
         { long: "--limit", value_name: "n", value_type: "number" },
@@ -813,6 +818,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-import",
       description:
         "Validate and idempotently merge a portable offline replica bundle.",
+      intent: "Validate and merge an offline digital-twin replica bundle.",
       flags: [
         {
           long: "--payload",
@@ -828,6 +834,7 @@ export function buildTwinCommands(): CommandDefinition[] {
       action: "twin-verify",
       description:
         "Verify checkpoint integrity, deterministic replay, topology, and invariants.",
+      intent: "Verify digital-twin replay, checkpoint, topology, and invariants.",
       flags: [{ long: "--at", value_name: "iso", value_type: "string" }],
       run: runVerify,
     },

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.13",
+  "version": "2026.8.14",
   "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/extensions/governance-audit/index.ts

@@ -327,6 +327,7 @@ function dedupeAuditCommand(): CommandDefinition {
     action: "dedupe-audit",
     description:
       "Audit likely duplicate items by title and parent scope heuristics.",
+    intent: "Find likely duplicate work without mutating the tracker.",
     flags: [...dedupeAuditFlags],
     run: async (context) =>
       runDedupeAuditPackage(context.options, context.global),
@@ -339,6 +340,7 @@ function dedupeMergeCommand(): CommandDefinition {
     action: "dedupe-merge",
     description:
       "Consolidate duplicates into a canonical item: re-parent active children and close duplicates with duplicate_of.",
+    intent: "Preview or apply an evidence-preserving duplicate consolidation.",
     flags: [...dedupeMergeFlags],
     run: async (context) =>
       runDedupeMergePackage(context.options, context.global),
@@ -350,6 +352,7 @@ function commentsAuditCommand(): CommandDefinition {
     name: "comments-audit",
     action: "comments-audit",
     description: "Audit item comment coverage and export comment history rows.",
+    intent: "Audit comment coverage and read bounded comment-history evidence.",
     flags: [...commentsAuditFlags],
     run: async (context) =>
       runCommentsAuditPackage(context.options, context.global),
@@ -361,6 +364,7 @@ function normalizeCommand(): CommandDefinition {
     name: "normalize",
     action: "normalize",
     description: "Plan/apply lifecycle metadata normalization sweeps.",
+    intent: "Preview or apply deterministic lifecycle metadata normalization.",
     flags: [...normalizeFlags],
     run: async (context) =>
       runNormalizePackage(context.options, context.global),

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

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

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -94,6 +94,7 @@ function guideCommand(): CommandDefinition {
     name: "guide",
     action: "guide",
     description: "Show migration and usage guidance for pm command families.",
+    intent: "Read focused local guidance for one pm workflow.",
     arguments: [
       { name: "topic", required: false, description: "Optional guide topic." },
     ],
@@ -108,6 +109,7 @@ function completionCommand(): CommandDefinition {
     name: "completion",
     action: "completion",
     description: "Generate shell completion scripts for bash, zsh, and fish.",
+    intent: "Generate a completion script for the selected shell.",
     arguments: [
       {
         name: "shell",
@@ -126,6 +128,7 @@ function completionTagsCommand(): CommandDefinition {
     name: "completion-tags",
     action: "completion-tags",
     description: "Print known tags for completion filters.",
+    intent: "List tag values for lazy shell completion.",
     run: async (context) => runCompletionTagsPackage(context.global),
   };
 }
@@ -135,6 +138,7 @@ function completionStatusesCommand(): CommandDefinition {
     name: "completion-statuses",
     action: "completion-statuses",
     description: "Print runtime status IDs for completion filters.",
+    intent: "List runtime status values for shell completion.",
     run: async (context) => runCompletionStatusesPackage(context.global),
   };
 }
@@ -144,6 +148,7 @@ function completionTypesCommand(): CommandDefinition {
     name: "completion-types",
     action: "completion-types",
     description: "Print runtime item type IDs for completion filters.",
+    intent: "List runtime item types for shell completion.",
     run: async (context) => runCompletionTypesPackage(context.global),
   };
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.8.13",
+  "version": "2026.8.14",
   "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.13",
+  "version": "2026.8.14",
   "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.13",
+  "version": "2026.8.14",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",