@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/docs/CONTEXT_ALGORITHM_PORTFOLIO.md

@@ -0,0 +1,167 @@
+# Context Algorithm Portfolio
+
+Tracked by [pm-g8t7b9](../.agents/pm/tasks/pm-g8t7b9.toon), [pm-4k6b](../.agents/pm/features/pm-4k6b.toon), and [pm-vvib](../.agents/pm/decisions/pm-vvib.toon).
+
+This is a navigation index of the historical algorithm ledger and cognitive proposals.
+Individual pm items own scope, decisions, experiments, and current evidence.
+A shared substrate or an earlier defect fix does not establish that a proposed
+ranking mechanism has been implemented. Read each owner live before claiming its state.
+
+## Bounded discovery
+
+```bash
+pm list --all --tags algorithm-proposal --limit 10
+pm search "<stable-slug>" --limit 5
+pm get <owner-id> --full
+pm history <owner-id> --full
+```
+
+Use the result cursor and omission receipt before making a complete-catalog claim.
+The four agent skills route to generated capability references; this portfolio
+does not add a new command family or a second execution backlog.
+
+## Algorithm ledger
+
+The 76 mechanisms below retain their original note timestamps and numeric aliases.
+An ordinal is ambiguous without its source note; new proposals use stable slugs.
+Where two descriptions express one experiment, both slugs resolve to its owner.
+Existing acceptance owners retain their original delivery boundary.
+
+| Stable slug | Historical ordinal | Source note (UTC) | Canonical owner | Disposition |
+| --- | --- | --- | --- | --- |
+| `act-r-activation` | 1 | 2026-07-07T15:12:12.161Z | [pm-fr9ok0](../.agents/pm/tasks/pm-fr9ok0.toon) | Proposed experiment |
+| `typed-spreading-activation` | 2 | 2026-07-07T15:12:12.161Z | [pm-fdb8e8](../.agents/pm/tasks/pm-fdb8e8.toon) | Proposed experiment |
+| `learned-linear-signal-weights` | 3 | 2026-07-07T15:12:12.161Z | [pm-ex5p2u](../.agents/pm/tasks/pm-ex5p2u.toon) | Proposed experiment |
+| `submodular-token-selection` | 4 | 2026-07-07T15:12:12.161Z | [pm-oadvw7](../.agents/pm/tasks/pm-oadvw7.toon) | Proposed experiment |
+| `reciprocal-rank-fusion` | 5 | 2026-07-07T15:26:05.199Z | [pm-h3no](../.agents/pm/tasks/pm-h3no.toon) | Existing acceptance owner |
+| `incremental-signal-fold` | 6 | 2026-07-07T15:26:05.199Z | [pm-801d](../.agents/pm/features/pm-801d.toon) | Existing acceptance owner |
+| `quota-bounded-retrieval-funnel` | 7 | 2026-07-07T15:37:10.972Z | [pm-v3grp9](../.agents/pm/tasks/pm-v3grp9.toon) | Proposed experiment |
+| `sketch-backed-affinity-state` | 8 | 2026-07-07T15:57:35.738Z | [pm-cxydzq](../.agents/pm/tasks/pm-cxydzq.toon) | Proposed experiment |
+| `granularity-adaptive-packing` | 9 | 2026-07-07T16:35:16.531Z | [pm-55ra](../.agents/pm/tasks/pm-55ra.toon) | Existing acceptance owner |
+| `structural-analogical-recall` | 10 | 2026-07-07T20:06:11.214Z | [pm-l4a5q9](../.agents/pm/tasks/pm-l4a5q9.toon) | Proposed experiment |
+| `open-loop-persistence` | 11 | 2026-07-07T20:26:24.821Z | [pm-u8rjvb](../.agents/pm/tasks/pm-u8rjvb.toon) | Proposed experiment |
+| `co-change-precedent-projection` | 12 | 2026-07-08T04:50:57.291Z | [pm-uk74i4](../.agents/pm/tasks/pm-uk74i4.toon) | Proposed experiment |
+| `salience-broadcast-habituation` | 13 | 2026-07-08T04:59:00.593Z | [pm-jd2wst](../.agents/pm/tasks/pm-jd2wst.toon) | Proposed experiment |
+| `retrieval-contradiction-gating` | 14 | 2026-07-08T22:51:13.305Z | [pm-xfta80](../.agents/pm/tasks/pm-xfta80.toon) | Proposed experiment |
+| `gist-verbatim-retention` | 15 | 2026-07-08T22:59:05.110Z | [pm-n7fpe8](../.agents/pm/tasks/pm-n7fpe8.toon) | Proposed experiment |
+| `successor-representation-map` | 16 | 2026-07-08T23:04:09.486Z | [pm-bj248h](../.agents/pm/tasks/pm-bj248h.toon) | Proposed experiment |
+| `learning-progress-exploration` | 17 | 2026-07-09T10:35:29.359Z | [pm-w0x318](../.agents/pm/tasks/pm-w0x318.toon) | Proposed experiment |
+| `deadline-anytime-assembly` | 18 | 2026-07-12T19:06:43.973Z | [pm-ltygoc](../.agents/pm/tasks/pm-ltygoc.toon) | Proposed experiment |
+| `intent-conditioned-profiles` | 19 | 2026-07-12T19:07:07.668Z | [pm-55ra](../.agents/pm/tasks/pm-55ra.toon) | Existing acceptance owner |
+| `temporal-era-segmentation` | 20 | 2026-07-13T17:49:16.342Z | [pm-tnkni6](../.agents/pm/tasks/pm-tnkni6.toon) | Proposed experiment |
+| `empirical-bayes-signal-shrinkage` | 21 | 2026-07-13T17:49:39.249Z | [pm-4lg7gl](../.agents/pm/tasks/pm-4lg7gl.toon) | Proposed experiment |
+| `lineage-relevance-continuity` | 22 | 2026-07-13T17:50:01.162Z | [pm-pyny5e](../.agents/pm/tasks/pm-pyny5e.toon) | Proposed experiment |
+| `consumer-conditioned-context` | 23 | 2026-07-24T23:56:51.483Z | [pm-oiml5g](../.agents/pm/tasks/pm-oiml5g.toon) | Proposed experiment |
+| `intent-ambiguity-hedging` | 24 | 2026-07-25T06:21:11.864Z | [pm-3t4fpz](../.agents/pm/tasks/pm-3t4fpz.toon) | Proposed experiment |
+| `description-length-stopping` | 25 | 2026-07-25T06:21:11.864Z | [pm-hnnsk4](../.agents/pm/tasks/pm-hnnsk4.toon) | Proposed experiment |
+| `fleet-shared-assembly` | 26 | 2026-07-25T06:21:11.864Z | [pm-tch9cs](../.agents/pm/features/pm-tch9cs.toon) | Existing acceptance owner |
+| `session-budget-allocation` | 27 | 2026-07-25T06:21:11.864Z | [pm-0d8cx0](../.agents/pm/tasks/pm-0d8cx0.toon) | Proposed experiment |
+| `model-conditioned-packing` | 19 | 2026-07-25T12:33:08.547Z | [pm-oiml5g](../.agents/pm/tasks/pm-oiml5g.toon) | Alias of `consumer-conditioned-context` |
+| `merge-probability-provenance` | 20 | 2026-07-25T12:33:09.924Z | [pm-2owmm9](../.agents/pm/tasks/pm-2owmm9.toon) | Proposed experiment |
+| `hash-keyed-summary-pyramid` | 21 | 2026-07-25T12:33:12.348Z | [pm-7go3ml](../.agents/pm/tasks/pm-7go3ml.toon) | Proposed experiment |
+| `counterfactual-replay-evaluation` | 22 | 2026-07-25T12:33:13.616Z | [pm-atfm](../.agents/pm/features/pm-atfm.toon) | Existing acceptance owner |
+| `federated-relevance-calibration` | 23 | 2026-07-25T17:55:26.153Z | [pm-p5x04j](../.agents/pm/tasks/pm-p5x04j.toon) | Proposed experiment |
+| `fleet-joint-diversification` | 24 | 2026-07-25T17:55:27.244Z | [pm-u7dei0](../.agents/pm/tasks/pm-u7dei0.toon) | Proposed experiment |
+| `outcome-distance-prior` | slug only | 2026-07-26T06:05:19.670Z | [pm-j915gx](../.agents/pm/tasks/pm-j915gx.toon) | Proposed experiment |
+| `maintenance-invariant-temporal-coordinates` | slug only | 2026-07-26T17:12:19.040Z | [pm-07pt16](../.agents/pm/issues/pm-07pt16.toon) | Existing acceptance owner |
+| `on-policy-context-evaluation-in-replayable-episodes` | slug only | 2026-07-26T22:10:55.488Z | [pm-atfm](../.agents/pm/features/pm-atfm.toon) | Existing acceptance owner |
+| `cited-substrate-churn-retention` | 28 | 2026-07-27T04:16:41.976Z | [pm-7xva2q](../.agents/pm/tasks/pm-7xva2q.toon) | Proposed experiment |
+| `ordering-slack-conditioned-urgency` | slug only | 2026-07-27T12:56:49.162Z | [pm-a795un](../.agents/pm/tasks/pm-a795un.toon) | Proposed experiment |
+| `recorded-order-arbitration` | slug only | 2026-07-28T15:06:04.775Z | [pm-6x7o](../.agents/pm/features/pm-6x7o.toon) | Existing acceptance owner |
+| `refuted-and-abandoned-evidence-retrieval` | slug only | 2026-07-28T22:37:05.155Z | [pm-j0hhum](../.agents/pm/tasks/pm-j0hhum.toon) | Proposed experiment |
+| `trust-weighted-context-assembly` | slug only | 2026-07-28T22:37:06.038Z | [pm-uzjalq](../.agents/pm/tasks/pm-uzjalq.toon) | Proposed experiment |
+| `omission-cost-asymmetric-ranking` | slug only | 2026-07-29T04:53:05.081Z | [pm-u64x78](../.agents/pm/tasks/pm-u64x78.toon) | Proposed experiment |
+| `absence-as-signal-coverage-complement` | slug only | 2026-07-29T04:53:05.081Z | [pm-qy48yz](../.agents/pm/tasks/pm-qy48yz.toon) | Proposed experiment |
+| `pinned-epoch-context-determinism` | slug only | 2026-07-29T04:53:05.081Z | [pm-8bgeye](../.agents/pm/features/pm-8bgeye.toon) | Existing acceptance owner |
+| `action-legality-conditioned-assembly` | slug only | 2026-07-29T16:59:47.781Z | [pm-cg9tgx](../.agents/pm/tasks/pm-cg9tgx.toon) | Proposed experiment |
+| `shape-conditioned-parameter-selection` | slug only | 2026-07-29T16:59:47.781Z | [pm-jxszo5](../.agents/pm/tasks/pm-jxszo5.toon) | Proposed experiment |
+| `cross-channel-disagreement-salience` | slug only | 2026-07-30T09:24:36.574Z | [pm-zhowns](../.agents/pm/tasks/pm-zhowns.toon) | Proposed experiment |
+| `budget-feasible-projection-descent` | slug only | 2026-07-30T17:12:42.066Z | [pm-yekkvt](../.agents/pm/issues/pm-yekkvt.toon) | Existing acceptance owner |
+| `co-mutation-cohort-inference` | slug only | 2026-07-31T06:12:41.171Z | [pm-8996e1](../.agents/pm/tasks/pm-8996e1.toon) | Proposed experiment |
+| `state-erased-signal-recovery` | slug only | 2026-07-31T14:19:33.829Z | [pm-oz1p2u](../.agents/pm/tasks/pm-oz1p2u.toon) | Proposed experiment |
+| `occupancy-interval-contention-inference` | slug only | 2026-08-01T09:51:18.539Z | [pm-ieskvz](../.agents/pm/tasks/pm-ieskvz.toon) | Proposed experiment |
+| `refusal-conditioned-retrieval-repair` | slug only | 2026-08-01T13:07:13.153Z | [pm-f6kmj2](../.agents/pm/tasks/pm-f6kmj2.toon) | Proposed experiment |
+| `citation-stable-evidence-addressing` | 23 | 2026-08-02T15:04:50.169Z | [pm-8bgeye](../.agents/pm/features/pm-8bgeye.toon) | Existing acceptance owner |
+| `convergence-confidence-weighting` | 24 | 2026-08-02T21:14:06.605Z | [pm-2owmm9](../.agents/pm/tasks/pm-2owmm9.toon) | Alias of `merge-probability-provenance` |
+| `session-marginal-relevance` | 25 | 2026-08-03T06:28:46.897Z | [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon) | Existing acceptance owner |
+| `recurrence-conditioned-retrieval` | 26 | 2026-08-03T20:40:23.212Z | [pm-x8cw63](../.agents/pm/tasks/pm-x8cw63.toon) | Proposed experiment |
+| `temporally-anchored-graph-proximity` | 27 | 2026-08-04T05:54:30.594Z | [pm-9lhtuf](../.agents/pm/tasks/pm-9lhtuf.toon) | Proposed experiment |
+| `act-conditioned-loss-asymmetry` | 28 | 2026-08-07T05:23:58.135Z | [pm-u64x78](../.agents/pm/tasks/pm-u64x78.toon) | Alias of `omission-cost-asymmetric-ranking` |
+| `structure-conditioned-signal-weighting` | 29 | 2026-08-07T11:23:09.664Z | [pm-77pz59](../.agents/pm/tasks/pm-77pz59.toon) | Proposed experiment |
+| `cost-priced-signal-admission` | 30 | 2026-08-07T17:23:07.639Z | [pm-ltygoc](../.agents/pm/tasks/pm-ltygoc.toon) | Alias of `deadline-anytime-assembly` |
+| `reader-writer-contract-change-salience` | 31 | 2026-08-08T08:04:42.076Z | [pm-h3l0th](../.agents/pm/tasks/pm-h3l0th.toon) | Proposed experiment |
+| `epoch-conditioned-evidence-confidence` | 32 | 2026-08-08T22:00:52.713Z | [pm-nh1348](../.agents/pm/tasks/pm-nh1348.toon) | Proposed experiment |
+| `coverage-ratio-conditioned-evidence` | 33 | 2026-08-09T06:06:13.120Z | [pm-hlf7ca](../.agents/pm/tasks/pm-hlf7ca.toon) | Proposed experiment |
+| `property-lifetime-evidence-retention` | 34 | 2026-08-09T13:39:47.942Z | [pm-n7u3he](../.agents/pm/tasks/pm-n7u3he.toon) | Proposed experiment |
+| `subscriber-weighted-salience` | 35 | 2026-08-09T20:05:21.715Z | [pm-stdu2g](../.agents/pm/tasks/pm-stdu2g.toon) | Proposed experiment |
+| `truthful-field-omission-receipts` | 36 | 2026-08-10T06:08:53.534Z | [pm-tld20c](../.agents/pm/issues/pm-tld20c.toon) | Existing acceptance owner |
+| `governance-invariant-topology-signals` | 37 | 2026-08-10T12:19:15.015Z | [pm-5wc91d](../.agents/pm/tasks/pm-5wc91d.toon) | Proposed experiment |
+| `canonical-graph-measurement-reuse` | 38 | 2026-08-10T16:10:50.473Z | [pm-atfm](../.agents/pm/features/pm-atfm.toon) | Existing acceptance owner |
+| `redundancy-discounted-structural-weight` | 39 | 2026-08-10T21:02:34.076Z | [pm-nmti7j](../.agents/pm/tasks/pm-nmti7j.toon) | Proposed experiment |
+| `kind-rarity-edge-weighting` | 40 | 2026-08-11T14:11:06.615Z | [pm-cpnzmc](../.agents/pm/tasks/pm-cpnzmc.toon) | Proposed experiment |
+| `reachability-basis-aware-lineage` | 41 | 2026-08-13T08:51:22.149Z | [pm-wsyj7k](../.agents/pm/tasks/pm-wsyj7k.toon) | Proposed experiment |
+| `distribution-gated-structural-weight` | 42 | 2026-08-13T14:32:56.524Z | [pm-77pz59](../.agents/pm/tasks/pm-77pz59.toon) | Alias of `structure-conditioned-signal-weighting` |
+| `coverage-preserving-budget-truncation` | 43 | 2026-08-13T21:15:51.685Z | [pm-mo38ao](../.agents/pm/tasks/pm-mo38ao.toon) | Proposed experiment |
+| `event-quantile-recency` | 44 | 2026-08-14T05:25:41.723Z | [pm-8ryvgm](../.agents/pm/tasks/pm-8ryvgm.toon) | Proposed experiment |
+| `retrieval-action-ranking` | 45 | 2026-08-16T10:35:34.761Z | [pm-ra49iv](../.agents/pm/tasks/pm-ra49iv.toon) | Proposed experiment |
+| `declared-summary-populations` | 46 | 2026-09-04T18:40:47.913Z | [pm-79gv6q](../.agents/pm/issues/pm-79gv6q.toon) | Existing acceptance owner |
+
+## Cognitive subsystem mapping
+
+The 18 candidate compositions from pm-vvib retain the architecture decision gate.
+Individual experiment drafts record the ideas without accepting that decision.
+
+| Candidate | Composition | Canonical owner |
+| --- | --- | --- |
+| 1 | Prospective memory | [pm-0uvib0](../.agents/pm/tasks/pm-0uvib0.toon) |
+| 2 | Metacognitive revalidation | [pm-ur2t9o](../.agents/pm/tasks/pm-ur2t9o.toon) |
+| 3 | Interference and belief revision | [pm-xfta80](../.agents/pm/tasks/pm-xfta80.toon) |
+| 4 | Novelty and returning-agent deltas | [pm-tuadp2](../.agents/pm/features/pm-tuadp2.toon) |
+| 5 | Receiver-relative handoff | [pm-isldic](../.agents/pm/tasks/pm-isldic.toon) |
+| 6 | Source monitoring | [pm-uzjalq](../.agents/pm/tasks/pm-uzjalq.toon) |
+| 7 | Failure-sensitive avoidance | [pm-u64x78](../.agents/pm/tasks/pm-u64x78.toon) |
+| 8 | Procedural acquisition | [pm-5ay6gn](../.agents/pm/tasks/pm-5ay6gn.toon) |
+| 9 | Encoding context and source situations | [pm-8bgeye](../.agents/pm/features/pm-8bgeye.toon) |
+| 10 | Chunking and representation selection | [pm-55ra](../.agents/pm/tasks/pm-55ra.toon) |
+| 11 | Analogical retrieval | [pm-l4a5q9](../.agents/pm/tasks/pm-l4a5q9.toon) |
+| 12 | Open-loop persistence | [pm-u8rjvb](../.agents/pm/tasks/pm-u8rjvb.toon) |
+| 13 | Episodic future thinking | [pm-uk74i4](../.agents/pm/tasks/pm-uk74i4.toon) |
+| 14 | Salience broadcast | [pm-jd2wst](../.agents/pm/tasks/pm-jd2wst.toon) |
+| 15 | Reconsolidation gating | [pm-xfta80](../.agents/pm/tasks/pm-xfta80.toon) |
+| 16 | Gist/verbatim retention | [pm-n7fpe8](../.agents/pm/tasks/pm-n7fpe8.toon) |
+| 17 | Predictive cognitive map | [pm-bj248h](../.agents/pm/tasks/pm-bj248h.toon) |
+| 18 | Learning-progress exploration | [pm-w0x318](../.agents/pm/tasks/pm-w0x318.toon) |
+
+## Shared experiment contract
+
+Each proposal names its source, bounded SDK contract, inputs, evaluation population,
+costs, deterministic fallback, and promotion or rejection rule. Compare against
+an unchanged baseline on held-out judgments. Report task success, critical-evidence
+omission, ranking quality, tokens, latency, memory, and rebuild cost separately.
+
+Use tiny, real-shaped, sparse/dense, returning-session, concurrent, and long-history
+fixtures. A smoke run cannot certify million-item performance or fleet convergence.
+Read and write through the public SDK; CLI and MCP remain adapters.
+
+Historical descriptions may contain hypotheses about optimality, independence, or
+constant-time behavior. Those are claims to test. State the assumptions required
+by an approximation guarantee, and preserve missing evidence as unknown.
+
+Promotion requires an explicit decision and passing current mandatory gates.
+A proposed experiment does not authorize a production policy, adaptive learning,
+or workspace-data export. Rejected experiments remain searchable evidence.
+
+## Mathematical checks before promotion
+
+- RRF's published offset of 60 was an empirical choice. Retain a deterministic
+  baseline and test alternatives; it is not a universal calibration constant.
+  [Cormack, Clarke, and Büttcher (2009)](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf).
+- A plain value-per-token greedy heuristic does not inherit every submodular
+  approximation guarantee. Sviridenko's knapsack result assumes a nonnegative,
+  nondecreasing submodular objective and uses partial enumeration with greedy
+  completion. Representation exclusivity and negative penalties need their own
+  analysis. [Sviridenko (2004)](https://www.sciencedirect.com/science/article/pii/S0167637703000622).
+- WL subtree features scale with edges and refinement rounds in the published
+  formulation. Our proposed use still needs bounded neighborhoods and an
+  evaluation of whether structural similarity predicts useful project evidence.
+  [Shervashidze et al. (2011)](https://www.jmlr.org/papers/v12/shervashidze11a.html).

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Diagnostic Output Contracts
 
-Tracker references: [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+Tracker references: [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), and [pm-m4uyyj](../.agents/pm/issues/pm-m4uyyj.toon).
 
 ## Agent Quick Context
 
@@ -77,8 +77,14 @@ The deterministic ladder is:
 
 Human diagnostics lead with `What is required` and next steps before explaining
 what happened. If their declared ceiling binds, the compact text still begins
-with the required action and points to structured JSON for the bounded recovery
-envelope.
+with the required action, retains the first identifying line (up to 320 UTF-8
+bytes), and points to structured JSON for the bounded recovery envelope. The
+first line should name the specific failure, such as `Error: Unknown option
+--label`. Oversized caller-input echoes are discarded before this identity;
+the retained identity and corrective action share the binding byte budget.
+The text projector strips terminal escape sequences and replaces remaining
+control characters before measuring output, including short diagnostics that
+fit the budget. Line breaks and ordinary indentation are preserved.
 
 ## Executable Assurance
 

package/docs/EXTENSIONS.md

@@ -16,6 +16,7 @@ pm package upgrade --dry-run
 Hidden `pm extension ...`, `pm install ...`, and `pm upgrade ...` aliases remain supported for compatibility. They execute the canonical package handlers, keep stdout machine-compatible, and emit one migration hint on stderr unless the public config key `ux_deprecation_hints` (stored at `ux.deprecation_hints`) is disabled. Related docs: [SDK](SDK.md), [Configuration](CONFIGURATION.md), [Testing](TESTING.md), [Command Reference](COMMANDS.md), [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md).
 
 ## Package Sources
+See [Install plans and update evidence](PACKAGE_EVIDENCE.md) for copy-cost planning and freshness semantics.
 
 `pm package install` accepts local, registry, and GitHub sources:
 

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.