@unbrained/pm-cli 2026.9.6 → 2026.9.8

package/docs/HISTORY_MAINTENANCE.md

@@ -0,0 +1,125 @@
+# History maintenance and recovery
+
+Tracked by [pm-34w8za](../.agents/pm/chores/pm-34w8za.toon) and
+[pm-tqel](../.agents/pm/tasks/pm-tqel.toon).
+
+History is authoritative context: maintenance must preserve replay integrity,
+version addresses, provenance, and retained recovery evidence. The SDK owns
+these policies; the CLI exposes the same operations through one history family.
+
+## Command paths
+
+| Native command | Permanent compatibility spelling | Purpose |
+| --- | --- | --- |
+| `pm history <id>` | unchanged | Read or verify one item stream |
+| `pm history activity` | `pm activity` | Read activity across streams |
+| `pm history redact <id>` | `pm history-redact <id>` | Remove selected sensitive content |
+| `pm history repair [id]` | `pm history-repair [id]` | Repair or salvage a stream using explicit policy |
+| `pm history compact [id]` | `pm history-compact [id]` | Retain a baseline and selected history tail |
+| `pm history restore <id> <timestamp-or-version>` | `pm restore <id> <timestamp-or-version>` | Restore an item's historical state |
+
+Compatibility commands remain executable with their existing flags and result
+shapes. Default discovery omits these root aliases. `pm --all --help` and full
+contracts retain the compatibility inventory. SDK function names and MCP action
+identifiers remain stable, including `history-repair` and `restore`.
+
+Bash, Zsh, and Fish completion expose the activity flags under both spellings,
+including `--unbounded`. The `--stream` mode is optional; Zsh offers `rows`,
+`ndjson`, and `jsonl` when a mode is supplied.
+Completion accepts global options before `history` and between `history` and
+its operation, including valued options such as `--pm-path <path>` and
+`--output-format=json`. Option values and later positional arguments do not
+select an operation; the first ordinary history argument remains the item ID.
+Zsh and Fish also offer the value-taking `--id` alternative for redaction,
+repair, and compaction under both native and compatibility spellings.
+
+```bash
+pm history repair --help
+pm contracts --command "history compact" --flags-only --json
+pm contracts --command "history restore" --availability-only --json
+pm history activity --limit 10
+pm history pm-example --verify --strict-exit
+pm history compact pm-example --dry-run
+pm history repair pm-example --dry-run
+```
+
+Maintenance previews do not write history or item files. Redaction, repair,
+and compaction return diagnostic report envelopes for both native and legacy
+spellings. Review the operation's report before applying a rewrite. Restore
+returns the standard flat mutation
+receipt; activity uses the existing bounded read envelope and streaming
+contracts. Universal output controls resolve against the selected leaf, so a
+restore does not inherit the parent history read envelope.
+SDK agent-task transcripts resolve the selected history operation through
+leading and interleaved global options before validating output and exit
+contracts. Native maintenance steps use diagnostic reports, restore uses a
+mutation receipt, and ordinary item history retains its collection contract.
+
+History identifiers must be a single filename: path separators, traversal-only
+names, null bytes, and drive or stream syntax are rejected before resolution.
+Bulk compaction thresholds must be non-negative safe integers, up to
+`9007199254740991`, in both CLI flags and SDK options. Invalid thresholds are
+rejected before scanning streams.
+`--min-entries` is a bulk-only threshold; single-ID compaction rejects it
+instead of silently ignoring it.
+
+Redaction diagnostics hide matcher and replacement values after resolving the
+leading command path through global options. Words such as `history` or
+`redact` appearing only as values of an unrelated command do not activate this
+privacy filter. Unknown flags still permit redaction before validation fails.
+
+## SDK integration
+
+Use `runHistoryRedact`, `runHistoryRepair`, `runHistoryCompact`, and `runRestore`
+from the public SDK for ordinary integrations. These functions retain each
+operation's validation, audit events, version mapping, and recovery policy.
+
+`runHistoryMaintenance` is the shared SDK pipeline for history transforms. It
+accepts a resolved subject, settings, type registry, operation policy, execution
+options, and a transform. The transform receives one captured stream, chain
+verification, current item, and resolved author. It returns planned entries,
+a result renderer, and optional transactional callbacks.
+
+The pipeline performs these steps:
+
+1. Read original bytes and decode entries from the same file read.
+2. Capture the current item and construct the operation-specific plan.
+3. Verify the complete planned chain, including during dry runs.
+4. For a changed apply, enforce ownership and acquire the existing rewrite lock.
+5. Recheck both stream and item bytes under that lock; reject concurrent changes.
+6. Persist with rollback, then collect post-write hook warnings and render the report.
+
+`readHistorySnapshot` exposes the paired raw bytes and decoded entries when an
+integration needs a concurrency baseline. `readHistoryEntries` remains the
+array-returning compatibility API.
+
+A custom `applyRewrite` callback owns any coupled item/history transaction and
+its rollback. `beforeWrite` runs under the lock for evidence checks, and
+`afterWrite` supplies operation-specific hook and index warnings. Planning must
+not persist changes. The shared pipeline verifies the planned chain but cannot
+make arbitrary callback side effects transactional.
+
+Redaction uses the coupled item/history transaction. Repair retains its
+source-bound abandonment and salvage policies. Compaction retains baseline,
+checkpoint, and historical version mappings. Restore uses the same snapshot
+and under-lock drift primitives while retaining its lifecycle transaction and
+unreadable-item recovery reader. Copy retains its existing SDK lifecycle
+implementation.
+
+## Verification
+
+The namespace integration tests compare native and compatibility previews and
+activity results, verify untouched bytes after previews, apply restore, and
+verify the resulting chain. SDK maintenance tests exercise invalid plans and
+concurrent changes. Existing redaction, repair, compaction, and restore suites
+continue to cover operation-specific rollback and retained evidence.
+
+Run tests through the sandbox wrapper described in [Testing](TESTING.md):
+
+```bash
+node scripts/run-tests.mjs test -- tests/integration/history-namespace.integration.spec.ts tests/unit/sdk/history/maintenance.spec.ts tests/unit/sdk/cli-contracts/history-namespace-completion.spec.ts
+```
+
+See [Mutation Integrity](MUTATION_INTEGRITY.md),
+[Context Integrity Contracts](CONTEXT_INTEGRITY_CONTRACTS.md), and
+[CLI Grammar](CLI_GRAMMAR.md) for the surrounding guarantees.

package/docs/MCP_2026_07_28_CONFORMANCE.md

@@ -15,17 +15,27 @@ evidence or an explicit open obligation.
 | No modern initialize, initialized notification, ping, or protocol session                          | [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon) | Implemented with bounded legacy stdio adapter                                                                            | modern removed-method and legacy handshake tests                                          |
 | Legacy interoperability covers every initialize-era revision the spec names   | [pm-edywqn](../.agents/pm/issues/pm-edywqn.toon)   | Implemented: `2025-11-25` and `2025-06-18` accepted, requested revision echoed                                            | `tests/integration/mcp-handshake.spec.ts` handshake matrix plus the plugin smoke `assertProtocolHandshakeMatrix` real-process gate and its negative control |
 | MRTR `input_required`, retry state, and reverse-request removal                                    | [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon)  | Implemented for SDK and stateless stdio adapter                                                                          | `tests/unit/sdk/mcp/interactions.spec.ts`; direct server negative controls                |
-| `subscriptions/listen`, request-scoped streams, no SSE resumability                                | [pm-v7e337](../.agents/pm/features/pm-v7e337.toon)  | Implemented locally; packed and published proof follows merge                                                            | subscription SDK, stdio, HTTP, backpressure, disconnect, and retry tests                  |
+| `subscriptions/listen`, request-scoped streams, no SSE resumability                                | [pm-v7e337](../.agents/pm/features/pm-v7e337.toon)  | Implemented; consumer acceptance remains a per-release gate                                                             | subscription SDK, stdio, HTTP, backpressure, disconnect, and retry tests                  |
 | Official `io.modelcontextprotocol/tasks` extension                                                 | [pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon)  | Implemented for eligible tool calls, durable lifecycle, and stdio methods; notifications remain with subscriptions owner | `tests/unit/sdk/mcp/tasks.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |
 | Cacheable list/read results, deterministic tools, JSON Schema 2020-12, any JSON structured content | [pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon)  | Implemented for current pm tool/resource/prompt surfaces                                                                 | SDK schema/cache tests and direct modern server surface suite                             |
-| Issuer-bound authorization, client metadata documents, consent, headers, OpenTelemetry             | [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon)  | Implemented locally; deployment verifier integration remains host-owned                                                   | authorization SDK adversarial tests, real HTTP bearer suite, and threat model             |
-| Stable MCP Apps negotiation, tool/resource metadata, fallback, sandboxing, and accessible views    | [pm-pznhee](../.agents/pm/features/pm-pznhee.toon)  | Implemented in the public SDK and stateless server; packed/published proof follows merge                                 | `tests/unit/sdk/mcp/apps.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`      |
-| Draft Skills over MCP list/get/read, compatibility, provenance, digests, bounds, and pagination    | [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon)  | Implemented against exact SEP-2640 draft revision; packed/published proof follows merge                                  | `tests/unit/sdk/mcp/skills.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |
+| Issuer-bound authorization, client metadata documents, consent, headers, OpenTelemetry             | [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon)  | Implemented; deployment-specific identity-provider verification remains host-owned                                       | authorization SDK adversarial tests, real HTTP bearer suite, and threat model             |
+| Stable MCP Apps negotiation, tool/resource metadata, fallback, sandboxing, and accessible views    | [pm-pznhee](../.agents/pm/features/pm-pznhee.toon)  | Implemented in the public SDK and stateless server; exact-version journeys run in the published-release verifier           | `tests/unit/sdk/mcp/apps.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`      |
+| Draft Skills over MCP list/get/read, compatibility, provenance, digests, bounds, and pagination    | [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon)  | Implemented against exact SEP-2640 draft revision; the published-release verifier checks negotiation and content digests   | `tests/unit/sdk/mcp/skills.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |
+| Per-request `io.modelcontextprotocol/logLevel`; omission forbids `notifications/message`          | [pm-pd7nh0](../.agents/pm/tasks/pm-pd7nh0.toon)    | SDK validates the eight severity values and rejects malformed metadata with `-32602`; pm emits no protocol log notifications | `tests/unit/sdk/mcp/protocol.spec.ts`, real stdio and Streamable HTTP negative controls |
 | Deprecated Roots, Sampling, Logging, HTTP+SSE, `includeContext`, dynamic registration              | [pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon)    | Canonical source ratcheted; bounded stdio adapter and dated migration policy remain                                      | generated inventory, negative controls, adapter tests, and migration guide                |
-| Official schema, real stdio/HTTP, packed/published, npx/bunx, negative controls                    | [pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon)     | Foundation implemented; remains open until every owner above closes                                                      | SDK/server suites, plugin smokes, published-release verifier                              |
+| Official schema, real stdio/HTTP, packed/published, npx/bunx, negative controls                    | [pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon)     | Conformance and released-consumer gates implemented; each release must produce its own acceptance evidence                 | SDK/server suites, plugin smokes, published-release verifier                              |
 
-The programme gate remains intentionally incomplete while local-only rows
-lack their packed and published evidence. Provider
-silence, a successful legacy initialize, or source-only unit coverage cannot
-promote such a row. Completion requires the owner's positive and negative
-tests plus exact packed and published consumer proof.
+This matrix describes implementation coverage, not a blanket certification of
+every deployed artifact. Programme completion requires each owner's positive
+and negative tests plus exact packed and published consumer proof for the
+revision being assessed. A source fix does not retroactively change a released
+package. Read the live programme item
+[pm-rs9vry](../.agents/pm/features/pm-rs9vry.toon) for outstanding obligations.
+
+Logging remains deprecated in the official revision. pm accepts its optional
+request metadata for interoperability but does not advertise logging support
+or emit `notifications/message`, even when a client opts in. The request-local
+threshold is exposed by `resolveMcpRequestContext` as `logLevel`; it is never
+inherited by the next request. Ordinary diagnostics continue through stderr or
+the configured telemetry path. See the normative
+[request metadata schema](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts).

package/docs/PACKAGE_EVIDENCE.md

@@ -0,0 +1,92 @@
+# Install Plans and Update Evidence
+
+Tracked by [pm-5bsofk](../.agents/pm/issues/pm-5bsofk.toon) and
+[pm-gf5zw8](../.agents/pm/issues/pm-gf5zw8.toon), with claim controls tracked by
+[pm-eqdo85](../.agents/pm/issues/pm-eqdo85.toon).
+
+## Install planning
+
+Preview an install with `pm package install ./local-package --project --dry-run`.
+The `details.install_plan` receipt distinguishes directory, archive, npm, and
+GitHub sources and reports logical file bytes, file/directory/link counts, and
+the copy policy. External local directories are directory snapshots, including
+development artifacts; nested destinations exclude `.agents`, `node_modules`,
+and installer backup directories at every depth using the installer's filter.
+Counts are lower bounds when `complete` is false, with `stop_reason`
+identifying the entry or depth limit. A source-directory alias resolves to its
+directory before copying; symlink entries inside the source remain links and
+their targets are never traversed.
+Planning writes no destination files, managed state, or activation settings;
+archive and remote source resolution can still prepare temporary source files
+and perform network or dependency-resolution work.
+
+For development-heavy or incomplete local snapshots, `packed_alternative`
+provides argument vectors for `npm pack --ignore-scripts --json` and archive
+installation. Run packing in its reported `cwd`, substitute the returned
+`pack_result[0].filename`, and install the resulting archive. Normal local
+installs also return their pre-copy plan. SDK callers can use
+`planExtensionDirectoryCopy(source, destination, { maxEntries, maxDepth, signal })`
+or `PmClient.packageInstall(source, { project: true, dryRun: true, copyPlan })`;
+the defaults inspect at most 10,000 entries and 64 directory levels.
+Strict MCP requests use `install`, `package-install`, or `extension-install`
+with `target` or `github` and `dryRun: true`. Generic `package` and `extension`
+requests also require `install: true` and a source when enabling `dryRun`.
+
+```bash
+pm package install ./local-package --project --dry-run --json
+npm pack --ignore-scripts --json
+pm package install ./package-name-1.0.0.tgz --project
+```
+
+Run the last two commands in the reported packing directory and substitute the
+actual archive filename. Packing applies the package's publish file selection;
+inspect that selection when a package needs generated assets at runtime.
+A plan is an observation, not a reservation: source files can change before
+the actual copy. Normal install verification remains authoritative.
+
+The SDK adds optional `copyPlan` controls and a typed optional
+`details.install_plan`. Custom result constructors that previously placed an
+unrelated value under that key must migrate to the declared plan type. Other
+extension detail fields retain their open record contract.
+
+The install-plan regression has a reproducible source-mutation control:
+
+```bash
+node scripts/release/package-install-plan-control.mjs
+node scripts/release/package-install-plan-control.mjs --negative-control
+```
+
+The baseline exits zero. The negative control changes only a disposable source
+copy to report a complete entry-limited scan, then runs the same real filesystem
+test and exits one. The linked control test requires both outcomes; the checkout
+and project tracker are never mutated by the control.
+
+Claim receipts and update coverage have matching baseline/mutant controls:
+
+```bash
+node scripts/release/lifecycle-evidence-control.mjs
+node scripts/release/lifecycle-evidence-control.mjs --negative-control
+node scripts/release/lifecycle-evidence-control.mjs --update-coverage
+node scripts/release/lifecycle-evidence-control.mjs --update-coverage --negative-control
+```
+
+Each baseline exits zero and each unsafe mutant exits one. The claim mutant
+disables compact MCP envelopes; the update mutant falsely reports full coverage
+for a skipped source. The linked test executes all four outcomes against real
+SDK behavior in disposable source copies.
+
+## Update verification
+
+Update coverage describes checks actually completed. `checked` entries alone
+contribute to known update counts; `skipped_unmanaged`, `skipped_non_github`,
+`failed`, and `not_checked` remain distinct in `update_check_status_totals`.
+Any actionable gap makes update coverage partial, even when no update is known.
+Adoption records provenance but does not establish upstream freshness for local
+or npm sources. Expected host-owned built-ins remain exempt from unmanaged
+adoption warnings and adoption remediation. Runtime activation health and update freshness are separate
+verdicts; inspect both before claiming that installed packages are current.
+
+Use `pm package doctor --project --detail deep --json` to inspect activation
+alongside update-check status totals. A strict doctor run may fail for partial
+update coverage even when activation succeeds. Empty scopes and applicable
+host-owned built-ins do not require third-party upstream checks.

package/docs/PLANNING_MEASUREMENTS.md

@@ -0,0 +1,183 @@
+# Planning measurements
+
+Tracked by [pm-6olc95](../.agents/pm/issues/pm-6olc95.toon),
+[pm-398z0u](../.agents/pm/issues/pm-398z0u.toon), and
+[pm-d2wfig](../.agents/pm/features/pm-d2wfig.toon). Distribution work is tracked
+by [pm-fx0rcb](../.agents/pm/tasks/pm-fx0rcb.toon).
+
+These SDK primitives make three planning questions reproducible: which recorded
+populations have relationship context, how many items belong to each category,
+and whether estimated prerequisite work fits an authored deadline. The CLI and
+MCP use the same SDK implementations.
+
+## Relationship coverage across lifecycle states
+
+```bash
+pm graph audit --summary
+pm graph audit --save-baseline --summary
+```
+
+`--summary` retains recorded population totals, acyclicity, and lifecycle
+connectivity counts. Use `--full` for degree histograms, status/type distributions,
+edge-kind shares, and reachability detail. Baselines always persist the full census.
+The summary omission receipt declares `--full` as the recovery path.
+
+`profile.coverage_by_lifecycle` reports `all`, `active`, and `terminal` populations.
+`profile.coverage_by_status` reports the actual schema statuses, including
+`closed`, `canceled`, and custom terminal states. Every population reports:
+
+- `nodes`: recorded items, excluding missing and external placeholders.
+- `isolated` and `degree_leq_one`: items with zero or at most one incident edge.
+- `semantic_nodes` and `without_semantic_edges`: presence or absence of incident
+  provenance or verification edges, using the audit's semantic-kind definition.
+- `degree_histogram`: exact incident directed-edge counts and their populations.
+
+The existing active-only counters and type profiles retain their meanings.
+Population measurements include policy-exempt isolates; exemptions affect
+findings, not census denominators. Incident edges use the assembled graph's
+normalized, deduplicated directed basis. Reciprocal spellings can still be
+reported separately by duplicate-edge findings.
+
+`ordering_acyclic` states whether the complete ordering graph is acyclic.
+`active_ordering_acyclic` states whether any detected ordering cycle touches
+active or unknown-lifecycle work. A historical cycle remains a structural cycle
+even when the historical-debt policy gives its finding informational severity.
+Missing-reference findings retain their separate active and terminal populations.
+
+After a saved baseline, signed lifecycle and status deltas measure backfill
+progress. An older baseline that never measured these populations reports
+`lifecycle_comparable: false`; it does not imply that the historical population
+was empty. Save a new baseline to begin comparable measurements. Malformed new
+census fields invalidate a persisted baseline rather than producing misleading
+comparisons. Rebuildable query-cache entries from the older format are discarded.
+
+## Group membership and bounded aggregation
+
+```bash
+pm aggregate --group-by tags --limit 20
+pm aggregate --group-by tags,type --sum estimated_minutes --completion
+pm aggregate --group-by tags --set-mode tuple
+```
+
+Set-valued dimensions group by distinct normalized members by default. An item
+with `alpha` and `beta` contributes once to each group, even if a member appears
+more than once or differs only in case or surrounding whitespace. The same
+expansion rule applies to every array-valued grouping dimension; scalar dimensions
+compose with those memberships. Empty sets retain a `null` group displayed as
+`(untagged)` for tags.
+
+`--set-mode tuple` selects the previous behavior: the complete normalized set is
+one comma-joined key. This is useful when comparing exact category combinations.
+It is a distinct operation, and `filters.set_mode` records the interpretation.
+
+Counts, completion rates, sums, and averages are computed independently in each
+membership group. Consequently, summing group counts or numeric sums can count
+one item more than once. `totals.items_grouped` counts distinct input items;
+`totals.group_memberships` counts all group contributions.
+
+Aggregation reads the complete matching item population before paging groups.
+An unreadable input fails the strict read rather than becoming a partial count.
+The default page contains at most 50 groups. `count` is the total group count,
+`returned_count` is the page size, and `truncated` indicates further groups.
+Pass the returned `next_after` value as `--after` to continue. Keep the grouping
+and filters unchanged between pages. A cursor absent from the current result is
+rejected with restart guidance; pages are not an immutable snapshot of a tracker
+that is being concurrently edited.
+
+## Derived deadline constraints
+
+```bash
+pm graph slack --limit 10
+pm graph slack --summary
+```
+
+The existing unit-weighted `rows`, `makespan`, and hop-based `slack` remain intact.
+The additional `deadline_schedule` uses `estimated_minutes` and authored
+`deadline` finish constraints. Its `basis` is `derived_elapsed_minutes`, and
+`as_of` records the clock used. This computation writes no item fields.
+
+A forward pass computes earliest estimated starts from the invocation clock. A
+backward pass transfers each dated finish constraint through the ordering graph,
+retaining the tightest successor constraint. A derived row identifies the
+controlling `deadline_id`, its `latest_start`, and `slack_minutes` relative to the
+earliest possible start. Negative slack indicates a time shortfall; this can
+coexist with positive hop-based slack.
+
+`overcommitted` findings name the authored deadline, the shortfall in minutes,
+and a bounded controlling prerequisite path. `path_truncated` identifies a path
+whose leading steps were omitted; the retained suffix still ends at the dated
+item. Moving the authored deadline later recomputes the finding.
+
+Missing, negative, or nonfinite estimates are explicit `unknown_estimate`
+residuals. Unknown predecessor duration produces `unknown_predecessor_estimate`
+and `null` temporal slack, never zero-cost feasibility. Cycles and work gated by
+cycles report `cycle_or_gated_by_cycle`. Invalid dates and dates outside the
+representable range are also residuals. `complete: false` means feasibility
+cannot be established for the entire input graph; counts remain separate from
+bounded samples.
+
+Estimates represent elapsed duration with independent work allowed in parallel.
+There is no staffing, resource-contention, working-hours, holiday, or progress
+model. The workspace adapter schedules active work and reports `population: active`;
+completed work no longer consumes future duration or contributes overdue deadlines.
+The pure SDK function schedules the supplied graph, so callers can select other
+populations explicitly. ISO
+date-only deadlines denote UTC midnight. Undated components have no latest-start
+constraint. Topology cache hits do not reuse time-sensitive deadline results;
+they are derived from the current metadata on every invocation.
+
+The pure derivation defaults to a work bound of 100,000 input items plus graph
+nodes and edges, checked before graph passes. Larger inputs return
+`work_limit_exceeded: true` and `complete: false` with no manufactured schedule.
+Rows, residual samples, findings, and path identifiers obey the supplied `limit`.
+All retained paths also share a total identifier budget of `maxWork`, so large
+finding limits cannot create quadratic path evidence. Exhaustion preserves exact
+counts and sets both `path_truncated` and the result's `truncated` flag.
+The workspace CLI still pays its existing metadata-read and graph-assembly cost;
+the derivation bound is not a claim that loading a million-item workspace is free.
+Summary mode suppresses the evidence arrays and retains their counts.
+
+## Public SDK
+
+```ts
+import {
+  assembleWorkspaceRelationshipGraph,
+  auditWorkspaceRelationshipGraph,
+  deriveRelationshipDeadlines,
+} from "@unbrained/pm-cli/sdk/graph";
+import { runAggregate } from "@unbrained/pm-cli/sdk/query";
+
+const items = [
+  { id: "work", title: "Prepare", status: "open", estimated_minutes: 60 },
+  {
+    id: "milestone", title: "Deliver", status: "open", blocked_by: "work",
+    estimated_minutes: 30, deadline: "2026-10-01T12:00:00Z",
+  },
+];
+const assembly = assembleWorkspaceRelationshipGraph(items);
+const coverage = auditWorkspaceRelationshipGraph(assembly).profile;
+const schedule = deriveRelationshipDeadlines(assembly.graph, items, {
+  now: "2026-10-01T10:00:00Z",
+  maxWork: 100_000,
+  limit: 20,
+});
+const categories = await runAggregate(
+  { groupBy: "tags", setMode: "element", limit: 20 },
+  { path: "/path/to/project/.agents/pm" },
+);
+```
+
+The derivation accepts an `AbortSignal`. Relationship orientation comes from the
+supplied graph registry, so custom ordering kinds and inverse spellings use the
+same execution semantics. MCP `pm_run` with `action: "aggregate"` accepts
+`options.setMode`, `options.limit`, and `options.after`. MCP `pm_graph` with
+`subcommand: "slack"` returns the same deadline evidence.
+
+## Distribution
+
+Build finalization compacts whitespace in retained runtime JavaScript modules.
+It preserves module paths and identifiers, keeps public declaration documentation,
+and composes source maps back to the original TypeScript for release symbolication.
+Existing bundled outputs remain unchanged by this pass. Source maps remain local
+release artifacts and are excluded from the npm packlist. Artifact size and file
+count ceilings are checked against the actual npm pack projection.

package/docs/README.md

@@ -52,6 +52,7 @@ pm guide release --json
 - [MCP Remote Transport, Authorization, and Migration](MCP_REMOTE_TRANSPORT_SECURITY.md) - Streamable HTTP operation, subscriptions, OAuth and trace boundaries, threat model, and deprecated-feature ratchet.
 - [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
+- [Context Algorithm Portfolio](CONTEXT_ALGORITHM_PORTFOLIO.md) - stable proposal slugs, historical aliases, individual owners, cognitive compositions, and experiment gates.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
 - [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
@@ -60,12 +61,14 @@ pm guide release --json
 - [Generated Refusal Closure Census](generated/REFUSAL_CLOSURE_CENSUS.md) - complete error-catalog join to executable refusal evidence and explicit uncovered obligations.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
+- [History Maintenance and Recovery](HISTORY_MAINTENANCE.md) - native history commands, permanent aliases, shared SDK transforms, and transactional recovery.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
 - [SDK Agent Environments](AGENT_ENVIRONMENTS.md) - calibrated observations, total verdicts, isolated episodes, and an executable public-SDK environment.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
+- [Planning Measurements](PLANNING_MEASUREMENTS.md) - lifecycle coverage, set-membership aggregation, and derived deadline constraints.
 - [Defect Recurrence and Boundary Evidence](DEFECT_RECURRENCE.md) - captured external samples, structured defect-escape evidence, incremental change-risk indexing, and executable recovery-producer census.
 - [Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md) - terminal-item recurrence, duplicate-intake routing, capability-aware reindex recovery, and target-aware generated test guidance.
 - [Trustworthy Context and Evidence Contracts](TRUSTWORTHY_CONTEXT_EVIDENCE.md) - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.

package/docs/RELEASING.md

@@ -99,6 +99,7 @@ Policy:
   manifest changed by version substitution alone, and only the generated
   changelog heading changed. Any other path or content still fails closed
 - `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
+- Release preparation passes `--date-from-version` with the target calendar version so the generated heading already has its UTC release date before the tag exists. This keeps the preparation commit consistent with canonical post-tag generation and the normal `main` changelog check.
 - 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`
 - after creating and pushing a new tag, auto-release waits for the tag-push `.github/workflows/release.yml` run to finish instead of dispatching a second publish workflow

package/docs/SCRIPTING.md

@@ -78,6 +78,27 @@ declaring every command's default token ceiling. Use `pm contracts --full
 with TOON- and JSON-specific token ceilings for every active core or package
 command.
 
+Claim receipts ([pm-eqdo85](../.agents/pm/issues/pm-eqdo85.toon)) also keep
+`claimed_by`, `previous_assignee`, and `forced`. Conditional contention adds
+`skipped`; ranked claims add `available` and `attempts`. The change count
+reflects ownership fields actually changed: an unchanged repeat or skipped
+claim reports zero and does not write a duplicate mutation event.
+
+```bash
+pm claim pm-a1b2 --json
+pm claim pm-a1b2 --if-available --json
+pm claim --next --json
+pm claim pm-a1b2 --full-changed-fields --json
+```
+
+Use `--full-changed-fields` to restore the complete item, `changed_fields`,
+and ranked-selection recommendation. `--id-only` returns only identity and
+status; `--quiet` suppresses stdout. Direct typed SDK `claim` and
+`claimNext` calls return the full result. Generic SDK/MCP actions use the
+compact transport contract and accept `fullChangedFields` or `idOnly`.
+Custom SDK claim runners may omit the optional `changed_fields` member;
+receipts without that evidence retain their existing envelope.
+
 JSON object field order is not an API. Consume fields by name. Read envelopes keep the stable pagination vocabulary `items`, `count`, `total`, `has_more`, and, when another page exists, `next_cursor`. The `filters` object echoes the effective query scope. Plain `pm list` and `pm search` are all-status reads and disclose `filters.status: "all"`; lifecycle-specific commands such as `pm list-open` remain explicit shortcuts.
 
 Projection flags intentionally change row shape. Use `--fields` when a script requires an exact subset, `--brief` or `--compact` only when the documented sparse shape is sufficient, and `--full` when linked metadata is required. Check `row_contract` on generic read surfaces that expose one; do not infer omitted fields as empty values.

package/docs/TESTING.md

@@ -50,6 +50,15 @@ children, then cleans the roots up. Instrumentation tests can still exercise
 Sentry initialization through their mocked module boundary; ordinary negative
 fixtures must never create production incidents from a developer host.
 
+Temporary directories must live outside the checkout and outside any ancestor
+workspace with initialized tracker data. The runner rejects a checkout-local
+temporary root, including a symlink alias, before starting build or test
+processes ([pm-bukwmy](../.agents/pm/issues/pm-bukwmy.toon)). If the default
+temporary filesystem is full, set `TMPDIR` (or `TEMP`/`TMP` on Windows) to an
+existing isolated scratch directory; an ignored directory inside the repository
+is not isolated. Filesystem fixtures must honor `node:os`'s `tmpdir()` and remove
+only the temporary directories they created.
+
 Public SDK changes additionally run semantic surface and import-cost contracts:
 
 ```bash
@@ -108,6 +117,20 @@ Use focused runs while iterating, then run coverage before closure when risk or
 
 ## CI Retry and Timeout Diagnostics
 
+Platform regressions from [pm-hrhfgi](../.agents/pm/issues/pm-hrhfgi.toon) and
+[pm-zk67yf](../.agents/pm/issues/pm-zk67yf.toon) have portable negative controls.
+Complete source scans process at most 32 item files per batch; the descriptor
+pressure fixture fails unbounded reads while requiring genuine permission
+failures to remain visible. The 10,000-item aggregation fixture separately
+verifies completeness before pagination. Git fixtures that assert exact bytes
+declare repository-local `core.autocrlf=false` and `core.eol=lf` so host defaults
+cannot change the restoration target. Send generated shell scripts through
+stdin (`bash -s`) so their size cannot exceed Windows command-line limits.
+Runtime compaction is tested through a
+real directory alias as well as its physical path, including original source
+mapping and repeated-compaction byte stability. These tests run in the full
+suite on the Nightly Validation platform matrix.
+
 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

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -6,10 +6,10 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | --- | --- | ---: | ---: |
 | `init` | workspace | 30 | 30 |
 | `config` | workspace | 36 | 36 |
-| `extension` | extensions | 53 | 53 |
-| `package` | extensions | 54 | 54 |
-| `packages` | extensions | 54 | 54 |
-| `install` | extensions | 26 | 26 |
+| `extension` | extensions | 54 | 54 |
+| `package` | extensions | 55 | 55 |
+| `packages` | extensions | 55 | 55 |
+| `install` | extensions | 27 | 27 |
 | `upgrade` | extensions | 29 | 29 |
 | `create` | intake | 100 | 100 |
 | `copy` | intake | 24 | 24 |
@@ -22,7 +22,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `list-blocked` | context | 84 | 84 |
 | `list-closed` | context | 84 | 84 |
 | `list-canceled` | context | 84 | 84 |
-| `aggregate` | context | 37 | 37 |
+| `aggregate` | context | 40 | 40 |
 | `context` | context | 45 | 45 |
 | `ctx` | context | 45 | 45 |
 | `get` | context | 30 | 30 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -11,7 +11,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 - Uncovered error codes: 346
 - Coverage fraction: 0.052055
 - Closed-domain probes: 19
-- Grammar probes: 94
+- Grammar probes: 97
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -211,7 +211,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 57 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 60 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.6",
+  "version": "2026.9.8",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.6",
+  "version": "2026.9.8",
   "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.9.6",
+  "version": "2026.9.8",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",