@unbrained/pm-cli 2026.8.13 → 2026.8.15

package/docs/RELEASING.md

@@ -24,7 +24,8 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon), and SDK-bound reliability
 classification [pm-dqtzva](../.agents/pm/issues/pm-dqtzva.toon).
 The local/hosted gate selection contract is tracked by
-[pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon).
+[pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon). Release-candidate analyzer
+provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon).
 
 ## Version Policy
 
@@ -80,6 +81,9 @@ Policy:
   creating an ordinal replacement; an already-successful run is recorded as
   recovered without republishing
 - 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
+  reviewed PR head with successful DeepScan and CodeFactor results
 - `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
 - protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
@@ -196,8 +200,9 @@ The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256
 
 4. Run the same release pipeline locally.
 
-Push the final implementation commit first, wait for DeepScan and CodeFactor to
-finish on that reviewed SHA, then run the canonical registry-owned preflight:
+Push the final implementation commit through a reviewed pull request first,
+wait for DeepScan and CodeFactor to finish on that reviewed SHA, then run the
+canonical registry-owned preflight:
 
 ```bash
 pnpm verify:preflight
@@ -207,7 +212,8 @@ The registry supplies the ordered executable plan, command arguments,
 environment, capture policy, and explicit skip policy. Its receipt distinguishes
 passed checks from declared skips. The same registry maps named PR, nightly,
 and release workflow gates; hosted-only entries must explain why no faithful
-local equivalent exists.
+local equivalent exists. Analyzer provenance is the first executable step, so
+an unreleasable candidate fails before build, coverage, or package work.
 
 The preflight includes the mandatory local hosted-analysis proof:
 
@@ -218,13 +224,44 @@ pnpm quality:hosted-analysis
 The gate accepts only DeepScan's explicit zero-new-issue status and
 CodeFactor's explicit no-issues result. Both contexts are required by `main`
 branch protection, and the release pipeline reruns the same immutable-tree
-proof. It reads the release commit first. When GitHub does not copy app results
+proof. The gate reads branch protection through REST first; if that transport
+is unavailable or its core API quota is exhausted, it queries the equivalent
+GraphQL rules across every cursor-paginated page and still requires one exact
+`main` rule with strict updates plus both analyzer contexts. Malformed,
+truncated, missing, or ambiguous admin policy data fails closed. GitHub Actions'
+ephemeral token cannot request the repository `Administration: read` permission
+required by both of those policy surfaces. When both admin transports reject
+that token, the gate uses the contents-readable `GET /branches/main` summary
+and requires that the exact candidate is the current protected branch head,
+protection is enabled and enforced, and CodeFactor plus DeepScan are effective
+required contexts. That summary intentionally cannot attest the admin-only
+strict-update setting: its receipt reports `strict: null`,
+`strict_verified: false`, and `verification_scope: effective_required_checks`
+instead of inventing a positive result. Exact or immutable identical-tree
+analyzer provenance remains mandatory and is emitted beside the policy receipt,
+so the restricted-token recovery cannot admit an unanalyzed or different-tree
+candidate. A maintainer token with administration-read access still verifies
+and reports `strict: true` through REST or paginated GraphQL. It reads the
+release commit first. When GitHub does not copy app results
 onto a merge commit, the gate may reuse a reviewed merge-parent or squash-PR
 head only when its immutable Git tree SHA exactly matches the release commit.
 Squash provenance additionally requires one unambiguous GitHub association to a
 closed PR merged into `main` with the release commit as its merge commit.
 Missing, ambiguous, or different-tree provenance fails closed.
 
+The supported default-branch arrival path is a reviewed pull request. A direct
+push to `main` is releasable only if both analyzers attached successful evidence
+to that exact commit; when they did not, the gate explicitly refuses the
+candidate instead of letting the next scheduled release discover the missing
+precondition after expensive work. CI runs `Release analyzer readiness (main)`
+on every product-relevant push to `main`, providing continuous visibility
+between release attempts. If GitHub's commit-association endpoint has not yet
+published a new merge, the gate reads the pull-request number from GitHub's
+standard merge message and accepts it only after the immutable PR resource
+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.
+
 ```bash
 # Read-only parity check
 pnpm release:pipeline:dry-run

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), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
 
 ## Agent Quick Context
 
@@ -31,6 +31,67 @@ 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
+recovery names a bounded budget increase when no declared row path can resume.
+
+Budget-compacted declared rows instead publish a bounded `outputCursor`
+continuation on every transport. The cursor resumes the first withheld row and
+rejects a command, path, row-total, or stable-identity mismatch. This gives SDK
+and package loops a recursive self-improvement primitive: consume a bounded
+page, update context, and continue without abandoning the ceiling.
+
+`context --explain-ranking` projects explanations to the focus rows actually
+served. `candidate_count` records the scorer population and `omitted_count`
+records explanations intentionally withheld, while each returned row retains
+its rank, baseline rank, score, and per-signal contributions. Explanation cost
+therefore scales with the answer rather than with the active workspace.
+
+Unknown-option recovery is likewise derived from the declared flag lexicon.
+The structured `option_scope` is `declared_on_path`, `declared_elsewhere`, or
+`declared_nowhere`; accepting command paths are included only for the second
+case, while the third names the nearest current-path spellings and explicitly
+terminates the otherwise-unbounded command search.
+
+## Executable recovery-reference coverage
+
+Structured refusal guidance is a forward-reference contract, not decorative
+text. `verifyPmRecoveryReferences` accepts obligations derived from real error
+envelopes and observations produced by executing a retry, resolving a declared
+command path, or linking prose to an already executed recovery. Its report
+includes the total obligation set, pass fraction, sorted findings, and stable
+coverage buckets for `suggested_retry`, `candidate_command`, `example`, and
+`next_step`, including zero-population buckets.
+
+The repository integration corpus drives real CLI refusals, executes the
+emitted retry in a temporary tracker, compares candidate commands with the
+unbounded runtime contract enumeration, and binds examples and next steps to
+those proofs. A seeded unreachable observation must lower the pass fraction
+and produce `unreachable_reference`. The same corpus is a provider-backed
+blocking assertion in `repository-context-quality`, so a well-formed but broken
+recovery promise cannot pass CI merely because its text or target flag exists.
+
 ## Row discovery and exact output receipts
 
 Row locations and encoding capabilities remain part of the SDK-owned read
@@ -85,6 +146,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
@@ -103,6 +170,26 @@ never succeeded. The same bounded pass classifies bare boolean and single-digit
 values across every recorded provenance dimension, publishes only aggregate
 harness/dimension/kind counts, and never echoes the historical value.
 
+`historyRepair` and `historyRepairAll` retain the detected history hash epoch
+instead of unconditionally upgrading it. `normalizeProvenance: true` adds a
+privacy-safe repair mode that removes invalid bounded observations and records
+only aggregate counts/classes in the synthetic audit event. The bulk form
+selects both drifted streams and streams requiring provenance normalization.
+
+Health results are self-indexing: every retained warning has a `findings` row
+with its owning check, stable code, severity, and either executable remediation
+or an explicit safe refusal. `failed_because` contains the exact warning tokens
+that decide `ok: false` and survives brief/summary projection. Extension health
+adds a host-version census by resolving the pm-cli package visible from each
+loaded extension; npm/pnpm duplicate-version skew is gate-failing while matching
+workspace-linked and deduplicated copies remain green.
+
+Linked file/doc add parsing uses one SDK allowlist. Whitespace-free filesystem
+paths and scheme-prefixed URLs remain positional even when a path or query
+contains `=`. Leading assignment syntax, including malformed URL-plus-note
+input, must use the declared `path`, `scope`, and `note` keys or fail before
+mutation.
+
 ## Replication and refusal gate
 
 `scripts/release/surface-replication-sets.json` declares replicated SDK, CLI, MCP, documentation, and test members. `pnpm quality:surface-replication` activates sets from the Git changeset, verifies every member invariant, and reports:
@@ -114,6 +201,12 @@ harness/dimension/kind counts, and never echoes the historical value.
 - an AST-derived denominator of identical named rule bodies, declared coverage,
   and a non-decreasing detected-cluster floor.
 
+Trigger entries may constrain a shared file with `changed_lines_contain_any`.
+The set then activates only when an added or removed diff line carries one of
+those contract markers. Missing diff evidence fails closed and activates the
+set, while an unrelated hunk in the same shared table does not force artificial
+edits across every replicated member.
+
 Query waivers directly with:
 
 ```bash

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.15"
   },
   "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.15",
       "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.15",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,17 +120,17 @@
     "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 && 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: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",
-    "quality:context-eval": "pnpm build && node scripts/release/context-eval-gate.mjs && node scripts/release/retrieval-eval-gate.mjs --negative-control && node scripts/release/retrieval-eval-gate.mjs && node scripts/release/agent-task-token-gate.mjs --negative-control && node scripts/release/agent-task-token-gate.mjs && pnpm quality:token-surface",
+    "quality:context-eval": "pnpm build && node scripts/release/repository-assurance.mjs repository-context-quality --trigger ci --json && pnpm quality:token-surface",
     "quality:agent-task-token": "pnpm build && node scripts/release/agent-task-token-gate.mjs",
     "quality:agent-task-token:update": "pnpm build && node scripts/release/agent-task-token-gate.mjs --update",
     "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.15",
   "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.15",
   "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.15",
   "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.15",
   "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.15",
   "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.15",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",