@unbrained/pm-cli 2026.8.31 → 2026.9.2

package/dist/sdk/merge/receipts.d.ts

@@ -1,4 +1,7 @@
+import type { Stats } from "node:fs";
 import type { ItemMergeConflictDecision, MergePreferredSide } from "./three-way.js";
+/** Return whether a receipt id is safe to expose in cleartext diagnostics. */
+export declare function isSafeReceiptId(value: string): boolean;
 /** One clone-local merge receipt with recoverable branch values. */
 export interface MergeDecisionReceipt {
     /** Receipt schema version. */
@@ -70,12 +73,50 @@ export interface MergeReceiptReport {
     /** ISO timestamp for the report. */
     generated_at: string;
 }
-/** Internal integrity scan result used by health without exposing malformed receipt contents. */
+/** Loss-aware merge receipt report for integrity gates and diagnostic adapters. */
+export interface MergeReceiptEvidenceReport {
+    /** Whether clone-local evidence resolved and every candidate was read and validated successfully. */
+    ok: boolean;
+    /** Whether clone-local evidence resolved and every discovered JSON candidate was read and validated successfully. */
+    complete: boolean;
+    /** Number of valid receipts returned. */
+    count: number;
+    /** Number of candidates rejected by bounded-file, schema, identity, or copy-consistency validation. */
+    invalid_evidence_count: number;
+    /** Bounded privacy-safe identities and reason codes for rejected evidence. */
+    invalid_evidence: MergeReceiptInvalidEvidence[];
+    /** Whether additional rejected evidence was omitted from the bounded detail list. */
+    invalid_evidence_truncated: boolean;
+    /** Whether the clone-local Git receipt directory was resolved successfully; always emitted by current implementations and optional for structural compatibility. */
+    clone_local_evidence_resolved?: boolean;
+    /** Receipts including recoverable values from the local clone only. */
+    receipts: MergeDecisionReceipt[];
+    /** ISO timestamp for the report. */
+    generated_at: string;
+}
+/** Loss-aware receipt inspection result that never exposes malformed file contents. */
 export interface MergeReceiptEvidenceScan {
     /** Valid receipts that passed bounded-file, schema, and identity validation. */
     receipts: MergeDecisionReceipt[];
     /** Number of JSON receipt candidates that could not be validated safely. */
     invalid_evidence_count: number;
+    /** Bounded privacy-safe identities and reason codes for rejected evidence. */
+    invalid_evidence: MergeReceiptInvalidEvidence[];
+    /** Whether additional rejected evidence was omitted from the bounded detail list. */
+    invalid_evidence_truncated: boolean;
+    /** Whether the clone-local Git receipt directory was resolved successfully; always emitted by current implementations and optional for structural compatibility. */
+    clone_local_evidence_resolved?: boolean;
+}
+/** Stable privacy-safe classification for one rejected receipt candidate or source. */
+export interface MergeReceiptInvalidEvidence {
+    /** Evidence store that produced the rejected candidate. */
+    evidence_source: "clone_local" | "durable" | "clone_local_and_durable";
+    /** Stable failure class suitable for remediation routing and graph analytics. */
+    reason: "directory_unreadable" | "candidate_not_bounded_regular_file" | "candidate_unreadable" | "candidate_invalid_json" | "schema_or_identity_invalid" | "copy_provenance_mismatch";
+    /** Receipt identity when the bounded filename itself is a valid receipt id. */
+    receipt_id?: string;
+    /** SHA-256 locator for an unsafe or malformed candidate filename. */
+    candidate_name_hash?: string;
 }
 declare function prepareReceiptSettlement(params: {
     receiptPath: string;
@@ -101,6 +142,7 @@ export declare function writeMergeReceipt(params: {
     mergedFieldHashes?: Record<string, string>;
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
+declare function receiptDirectoryFailureMeansAbsent(directory: string, error: unknown, inspectAncestor?: (ancestor: string) => Promise<Pick<Stats, "isDirectory">>): Promise<boolean>;
 /** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
 export declare function inspectMergeReceiptEvidence(cwd: string, options?: {
     /** Include receipts whose reconciliation state is already settled. */
@@ -134,8 +176,16 @@ export declare function runMergeReceiptReport(options: {
     /** Repository directory to inspect; defaults to the process working directory. */
     cwd?: string;
 }): Promise<MergeReceiptReport>;
+/** Inspect every receipt candidate and retain completeness diagnostics without exposing rejected file contents. */
+export declare function runMergeReceiptEvidenceReport(options: {
+    /** Include receipts already represented by merge history events. */
+    includeReconciled?: boolean;
+    /** Repository directory to inspect; defaults to the process working directory. */
+    cwd?: string;
+}): Promise<MergeReceiptEvidenceReport>;
 /** Test-only seams for deterministic receipt-boundary fault coverage. */
 export declare const _testOnlyMergeReceipts: {
     prepareReceiptSettlement: typeof prepareReceiptSettlement;
+    receiptDirectoryFailureMeansAbsent: typeof receiptDirectoryFailureMeansAbsent;
 };
 export {};

package/dist/sdk/merge/receipts.js

@@ -7,13 +7,13 @@
  * value for the coordinator that performed the merge.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="145a6d31-5e14-5b0b-95fb-6f837d11e2f4")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="df7d5bd9-8381-5961-bda1-9e8ed335afc9")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { readdir } from "node:fs/promises";
+import { readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
-import { ensureDir, isFileAbsentError, pathExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
+import { ensureDir, isFileAbsentError, isFileMissingError, pathExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
 import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
 import { isRfc3339DateTime, nowIso } from "../../core/shared/time.js";
 import { readBoundedRegularFile } from "./receipt-file-boundary.js";
@@ -24,6 +24,7 @@ const RECEIPT_FIELD_MAX = 2_048;
 const RECEIPT_FILE_MAX_BYTES = 16 * 1024 * 1024;
 const RECEIPT_VALUE_MAX_DEPTH = 64;
 const RECEIPT_VALUE_MAX_NODES = 100_000;
+const RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT = 100;
 const RECEIPT_KEYS = new Set([
     "version",
     "id",
@@ -42,6 +43,10 @@ const RECEIPT_KEYS = new Set([
     "value_availability",
     "evidence_source",
 ]);
+/** Return whether a receipt id is safe to expose in cleartext diagnostics. */
+export function isSafeReceiptId(value) {
+    return RECEIPT_ID_PATTERN.test(value);
+}
 const RECEIPT_DECISION_KEYS = new Set([
     "field",
     "base",
@@ -163,7 +168,7 @@ function hasValidReceiptIdentity(value) {
     return !hasOnlyKeys(value, RECEIPT_KEYS) || value.version !== 1
         ? false
         : typeof value.id === "string" &&
-            RECEIPT_ID_PATTERN.test(value.id) &&
+            isSafeReceiptId(value.id) &&
             typeof value.item_id === "string" &&
             RECEIPT_ITEM_ID_PATTERN.test(value.item_id) &&
             isSafeReceiptItemPath(value.item_path, value.item_id);
@@ -367,59 +372,120 @@ export async function writeMergeReceipt(params) {
     return receipt;
 }
 async function readReceiptsFromDirectory(directory, evidenceSource) {
-    if (!(await pathExists(directory))) {
-        return { receipts: [], invalid_evidence_count: 0 };
-    }
     let names;
     try {
         names = await readdir(directory);
     }
-    catch {
-        return { receipts: [], invalid_evidence_count: 1 };
+    catch (error) {
+        const absent = await receiptDirectoryFailureMeansAbsent(directory, error);
+        return {
+            receipts: [],
+            invalid_evidence_count: absent ? 0 : 1,
+            invalid_evidence: absent
+                ? []
+                : [{ evidence_source: evidenceSource, reason: "directory_unreadable" }],
+            invalid_evidence_truncated: false,
+        };
     }
     const receipts = [];
     let invalidEvidenceCount = 0;
+    const invalidEvidence = [];
+    const recordInvalidEvidence = (name, reason) => {
+        invalidEvidenceCount += 1;
+        if (invalidEvidence.length >= RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT)
+            return;
+        const receiptId = name.slice(0, -".json".length);
+        invalidEvidence.push({
+            evidence_source: evidenceSource,
+            reason,
+            ...(isSafeReceiptId(receiptId)
+                ? { receipt_id: receiptId }
+                : { candidate_name_hash: sha256Hex(name) }),
+        });
+    };
     for (const name of names.sort((left, right) => left.localeCompare(right))) {
         if (!name.endsWith(".json"))
             continue;
+        const candidate = await inspectReceiptCandidate(directory, name, evidenceSource);
+        if (candidate.receipt !== undefined) {
+            receipts.push(candidate.receipt);
+        }
+        else {
+            recordInvalidEvidence(name, candidate.reason);
+        }
+    }
+    return {
+        receipts,
+        invalid_evidence_count: invalidEvidenceCount,
+        invalid_evidence: invalidEvidence,
+        invalid_evidence_truncated: invalidEvidenceCount > invalidEvidence.length,
+    };
+}
+async function receiptDirectoryFailureMeansAbsent(directory, error, inspectAncestor = stat) {
+    if (!isFileMissingError(error))
+        return false;
+    let ancestor = directory;
+    while (true) {
         try {
-            const receiptPath = path.join(directory, name);
-            const raw = await readBoundedRegularReceiptFile(receiptPath);
-            if (raw === null) {
-                invalidEvidenceCount += 1;
-                continue;
-            }
-            const parsed = JSON.parse(raw);
-            if (!isMergeDecisionReceipt(parsed, evidenceSource) ||
-                name !== receiptFileName(parsed.id)) {
-                invalidEvidenceCount += 1;
-                continue;
-            }
-            const { preferred: legacyPreference, evidence_source: _serializedEvidenceSource, ...receiptWithoutRuntimeKeys } = parsed;
-            const normalizedReceipt = {
-                ...receiptWithoutRuntimeKeys,
-                requested_preference: parsed.requested_preference ?? legacyPreference ?? "ours",
-                conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
-                evidence_source: evidenceSource,
-            };
-            receipts.push(normalizedReceipt);
+            return (await inspectAncestor(ancestor)).isDirectory();
         }
-        catch {
-            invalidEvidenceCount += 1;
+        catch (ancestorError) {
+            if (!isFileMissingError(ancestorError))
+                return false;
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                return true;
+            ancestor = parent;
         }
     }
-    return { receipts, invalid_evidence_count: invalidEvidenceCount };
+}
+async function inspectReceiptCandidate(directory, name, evidenceSource) {
+    let raw;
+    try {
+        raw = await readBoundedRegularReceiptFile(path.join(directory, name));
+    }
+    catch {
+        return { reason: "candidate_unreadable" };
+    }
+    if (raw === null)
+        return { reason: "candidate_not_bounded_regular_file" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { reason: "candidate_invalid_json" };
+    }
+    if (!isMergeDecisionReceipt(parsed, evidenceSource) ||
+        name !== receiptFileName(parsed.id)) {
+        return { reason: "schema_or_identity_invalid" };
+    }
+    const { preferred: legacyPreference, evidence_source: _serializedEvidenceSource, ...receiptWithoutRuntimeKeys } = parsed;
+    return {
+        receipt: {
+            ...receiptWithoutRuntimeKeys,
+            requested_preference: parsed.requested_preference ?? legacyPreference ?? "ours",
+            conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
+            evidence_source: evidenceSource,
+        },
+    };
 }
 /** Inspect valid receipts and count invalid evidence without returning untrusted file contents. */
 export async function inspectMergeReceiptEvidence(cwd, options = {}) {
     const directory = await resolveReceiptDirectory(cwd);
     const local = directory === null
-        ? { receipts: [], invalid_evidence_count: 0 }
+        ? {
+            receipts: [],
+            invalid_evidence_count: 0,
+            invalid_evidence: [],
+            invalid_evidence_truncated: false,
+        }
         : await readReceiptsFromDirectory(directory, "clone_local");
     const trackerRoot = options.pmRoot ?? path.join(cwd, ".agents", "pm");
     const durable = await readReceiptsFromDirectory(durableReceiptDirectory(trackerRoot), "durable");
     const receipts = new Map(durable.receipts.map((receipt) => [receipt.id, receipt]));
     let divergentCopyCount = 0;
+    const divergentCopyEvidence = [];
     for (const receipt of local.receipts) {
         const durableCopy = receipts.get(receipt.id);
         if (durableCopy !== undefined &&
@@ -427,6 +493,16 @@ export async function inspectMergeReceiptEvidence(cwd, options = {}) {
                 receiptProvenanceFingerprint(receipt)) {
             receipts.delete(receipt.id);
             divergentCopyCount += 1;
+            if (local.invalid_evidence.length +
+                durable.invalid_evidence.length +
+                divergentCopyEvidence.length <
+                RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT) {
+                divergentCopyEvidence.push({
+                    evidence_source: "clone_local_and_durable",
+                    reason: "copy_provenance_mismatch",
+                    receipt_id: receipt.id,
+                });
+            }
             continue;
         }
         receipts.set(receipt.id, durableCopy === undefined
@@ -441,6 +517,18 @@ export async function inspectMergeReceiptEvidence(cwd, options = {}) {
         invalid_evidence_count: local.invalid_evidence_count +
             durable.invalid_evidence_count +
             divergentCopyCount,
+        invalid_evidence: [
+            ...local.invalid_evidence,
+            ...durable.invalid_evidence,
+            ...divergentCopyEvidence,
+        ].slice(0, RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT),
+        invalid_evidence_truncated: local.invalid_evidence_truncated ||
+            durable.invalid_evidence_truncated ||
+            local.invalid_evidence_count +
+                durable.invalid_evidence_count +
+                divergentCopyCount >
+                RECEIPT_INVALID_EVIDENCE_DETAIL_LIMIT,
+        clone_local_evidence_resolved: directory !== null,
     };
 }
 /** Read clone-local receipts with explicit reconciled/lossless classification controls. */
@@ -524,7 +612,30 @@ export async function runMergeReceiptReport(options) {
         generated_at: nowIso(),
     };
 }
+/** Inspect every receipt candidate and retain completeness diagnostics without exposing rejected file contents. */
+export async function runMergeReceiptEvidenceReport(options) {
+    const evidence = await inspectMergeReceiptEvidence(options.cwd ?? process.cwd(), {
+        ...options,
+        includeLossless: true,
+    });
+    const complete = evidence.clone_local_evidence_resolved === true &&
+        evidence.invalid_evidence_count === 0;
+    return {
+        ok: complete,
+        complete,
+        count: evidence.receipts.length,
+        invalid_evidence_count: evidence.invalid_evidence_count,
+        invalid_evidence: evidence.invalid_evidence,
+        invalid_evidence_truncated: evidence.invalid_evidence_truncated,
+        clone_local_evidence_resolved: evidence.clone_local_evidence_resolved,
+        receipts: evidence.receipts,
+        generated_at: nowIso(),
+    };
+}
 /** Test-only seams for deterministic receipt-boundary fault coverage. */
-export const _testOnlyMergeReceipts = { prepareReceiptSettlement };
+export const _testOnlyMergeReceipts = {
+    prepareReceiptSettlement,
+    receiptDirectoryFailureMeansAbsent,
+};
 //# sourceMappingURL=receipts.js.map
-//# debugId=145a6d31-5e14-5b0b-95fb-6f837d11e2f4
+//# debugId=df7d5bd9-8381-5961-bda1-9e8ed335afc9

package/dist/sdk/merge/three-way.d.ts

@@ -28,7 +28,9 @@ export interface HistoryMergeResult {
  * hash re-anchored so the resulting chain verifies again. No side's events are
  * ever discarded: content divergence is preserved for the post-merge
  * reconciliation pass (`pm validate` + `pm history-repair`) instead of being
- * silently resolved by last-writer-wins.
+ * silently resolved by last-writer-wins. If either suffix cannot apply after
+ * deterministic ordering, the merge fails closed instead of publishing a
+ * hash-valid stream that omitted a branch effect.
  */
 export declare function mergeHistoryStreams(baseRaw: string, oursRaw: string, theirsRaw: string): HistoryMergeResult;
 /** Documents the relationship event stream merge result payload exchanged by command, SDK, and package integrations. */

package/dist/sdk/merge/three-way.js

@@ -9,7 +9,7 @@
  * definition for multi-branch agent workflows.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="393f6460-bf8b-5479-8e3e-cac6f2680823")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7e8fcddf-09fe-5979-b23a-78915bf7f896")}catch(e){}}();
 import { historyEntriesToRaw, reanchorHistoryEntries, } from "../../core/history/replay.js";
 import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "../../core/item/item-format.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -69,7 +69,9 @@ function commonHistoryPrefixLength(ours, theirs) {
  * hash re-anchored so the resulting chain verifies again. No side's events are
  * ever discarded: content divergence is preserved for the post-merge
  * reconciliation pass (`pm validate` + `pm history-repair`) instead of being
- * silently resolved by last-writer-wins.
+ * silently resolved by last-writer-wins. If either suffix cannot apply after
+ * deterministic ordering, the merge fails closed instead of publishing a
+ * hash-valid stream that omitted a branch effect.
  */
 export function mergeHistoryStreams(baseRaw, oursRaw, theirsRaw) {
     parseHistoryJsonl(baseRaw, "base");
@@ -126,10 +128,10 @@ export function mergeHistoryStreams(baseRaw, oursRaw, theirsRaw) {
         }
         return historyEntryIdentity(left).localeCompare(historyEntryIdentity(right));
     });
-    const reanchored = reanchorHistoryEntries([
-        ...ours.slice(0, shared),
-        ...mergedSuffix,
-    ]);
+    const reanchored = reanchorHistoryEntries([...ours.slice(0, shared), ...mergedSuffix], undefined, { continuousHashSurface: true });
+    if (reanchored.skippedOps > 0) {
+        throw new PmCliError(`History union cannot preserve ${reanchored.skippedOps} patch operation(s) after deterministic suffix ordering; leave the file unresolved for manual recovery.`, EXIT_CODE.GENERIC_FAILURE);
+    }
     return {
         merged: historyEntriesToRaw(reanchored.entries),
         strategy: "union_reanchor",
@@ -704,4 +706,4 @@ export function mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     };
 }
 //# sourceMappingURL=three-way.js.map
-//# debugId=393f6460-bf8b-5479-8e3e-cac6f2680823
+//# debugId=7e8fcddf-09fe-5979-b23a-78915bf7f896

package/dist/sdk/runtime-extended-actions.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="95e9def9-3f48-5108-8a17-0747fcf64f2d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="41227e35-6354-5208-997b-e8a1cf696bf9")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { transferMutationStdinTokenPolicy } from "./runtime-primitives.js";
@@ -9,7 +9,7 @@ import { runEval } from "./eval.js";
 import { runMergeDriver } from "./merge/driver.js";
 import { runMergeInstall } from "./merge/install.js";
 import { runMergeReconcile } from "./merge/reconcile.js";
-import { runMergeReceiptReport } from "./merge/receipts.js";
+import { runMergeReceiptEvidenceReport } from "./merge/receipts.js";
 import { listMutationEvents } from "./mutation-events.js";
 import { parseRuntimeInteger, readRuntimeString, readRuntimeStringArray, } from "./runtime-input.js";
 import { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
@@ -87,7 +87,7 @@ export function runRuntimeMergeAction(context) {
         }, context.global);
     }
     if (subcommand === "report") {
-        return runMergeReceiptReport({
+        return runMergeReceiptEvidenceReport({
             includeReconciled: input.includeReconciled === true,
             cwd: readRuntimeString(input, "cwd"),
         });
@@ -175,4 +175,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=95e9def9-3f48-5108-8a17-0747fcf64f2d
+//# debugId=41227e35-6354-5208-997b-e8a1cf696bf9

package/docs/AGENT_GUIDE.md

@@ -4,18 +4,25 @@ This guide is optimized for coding agents that need to understand and mutate rep
 
 ## Agent Quick Context
 
-Run this before heavy work:
+Run this before heavy work. The first call is the canonical cold start. Then run the request-specific duplicate and ownership checks before item mutation:
 
 ```bash
-pm context --limit 10
+pm context --limit 10 --for orient
 pm search "<request keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
+```
+
+Run the optional guidance setup commands only when needed:
+
+```bash
 pm init --agent-guidance status
 pm package install guide-shell --project
 pm guide workflows
 ```
 
+The completed-task replay gate selects that one-call protocol from equivalent fixed-corpus candidates: 1,055 estimated tokens versus 2,293 for the historical four-read sequence and 4,798 for `contracts --summary` plus `next`. The reviewed numbers and per-step receipts live in [the published token baseline](agent-task-token-baseline.json).
+
 If a relevant item exists, reuse it. If not, create a parent lineage, then create and claim the child implementation item.
 When AGENTS/CLAUDE guidance is missing, use `pm init --agent-guidance add` to inject compact workflow guardrails, or `pm init --agent-guidance skip` to persist an explicit decline.
 
@@ -26,7 +33,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 1. **Orient**
 
 ```bash
-pm context --limit 10
+pm context --limit 10 --for orient
 pm search "<keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
@@ -108,6 +115,7 @@ pm release <item-id>
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | The single next action + why         | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
 | Next ready work in one epic          | `pm next --parent <id>`                                                                                                                                    |
+| Canonical cold-start orientation     | `pm context --limit 10 --for orient` (1,055 estimated tokens on the fixed 101-item replay corpus)                                                          |
 | Next work and agenda                 | `pm context --limit 10`                                                                                                                                    |
 | Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap)                                                                                          |
 | Status of one epic/subtree           | `pm context --parent <id> --depth deep`                                                                                                                    |

package/docs/ARCHITECTURE.md

@@ -56,9 +56,12 @@ src/
     shared/
   mcp/
     server.ts
+    tool-definitions.ts
   sdk/
     cli-contracts.ts
     index.ts
+    mcp/
+      discovery.ts
   types/
 tests/
   unit/
@@ -287,6 +290,8 @@ allowance file:
 Do not add new CLI/MCP behavior by deep-importing `src/core`. Add or extend an
 SDK primitive first, then consume that SDK surface from the presentation layer.
 
+Progressive tool discovery follows this boundary directly: `src/sdk/mcp/discovery.ts` owns ranking, authorization filtering, budgets, cursors, omissions, cache identity, and the canonical result contract. `src/mcp/server.ts` only negotiates the extension, selects the entry catalog, and adapts compatibility text. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 ## Telemetry Schema Negotiation
 
 Telemetry preserves wire compatibility through an explicit client/server negotiation split:

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -55,7 +55,7 @@ This clones the repo, reads `.claude-plugin/marketplace.json` at the root, insta
 claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp
 ```
 
-Gives you the 31 MCP tools without skills or slash commands.
+Gives you the 32 MCP tools without skills or slash commands.
 
 ### 3. Direct project `.mcp.json` (project-scoped MCP only)
 
@@ -117,7 +117,7 @@ pnpm smoke:claude-plugin
 ```
 
 Verifies: plugin file structure, manifest name consistency, stateless MCP
-discovery for `2026-07-28`, 31 tools present, full workflow (init → create →
+discovery for `2026-07-28`, 32 tools present, full workflow (init → create →
 claim → update → link files/docs/tests → get → context → search → validate →
 health), and session-start hook.
 

package/docs/CONTEXT_RECOVERY_PRIMITIVES.md

@@ -1,6 +1,6 @@
 # Context Integrity and Recovery Primitives
 
-Tracker: [pm-hu92i3](../.agents/pm/issues/pm-hu92i3.toon), [pm-nc94mk](../.agents/pm/issues/pm-nc94mk.toon), [pm-xrjy8o](../.agents/pm/issues/pm-xrjy8o.toon), [pm-f60039](../.agents/pm/issues/pm-f60039.toon), [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon), [pm-z1z96w](../.agents/pm/issues/pm-z1z96w.toon), [pm-yhle2e](../.agents/pm/issues/pm-yhle2e.toon), [pm-t7wl00](../.agents/pm/issues/pm-t7wl00.toon), [pm-hiqlkh](../.agents/pm/issues/pm-hiqlkh.toon), [pm-ntnv4k](../.agents/pm/issues/pm-ntnv4k.toon), [pm-sxg7wl](../.agents/pm/issues/pm-sxg7wl.toon), [pm-xspd](../.agents/pm/chores/pm-xspd.toon)
+Tracker: [pm-dn8rwl](../.agents/pm/issues/pm-dn8rwl.toon), [pm-r97901](../.agents/pm/issues/pm-r97901.toon), [pm-hu92i3](../.agents/pm/issues/pm-hu92i3.toon), [pm-nc94mk](../.agents/pm/issues/pm-nc94mk.toon), [pm-xrjy8o](../.agents/pm/issues/pm-xrjy8o.toon), [pm-f60039](../.agents/pm/issues/pm-f60039.toon), [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon), [pm-z1z96w](../.agents/pm/issues/pm-z1z96w.toon), [pm-yhle2e](../.agents/pm/issues/pm-yhle2e.toon), [pm-t7wl00](../.agents/pm/issues/pm-t7wl00.toon), [pm-hiqlkh](../.agents/pm/issues/pm-hiqlkh.toon), [pm-ntnv4k](../.agents/pm/issues/pm-ntnv4k.toon), [pm-sxg7wl](../.agents/pm/issues/pm-sxg7wl.toon), [pm-xspd](../.agents/pm/chores/pm-xspd.toon)
 
 `project management = context management`: a successful command is useful only when the context it records and later returns is truthful, lossless, and actionable. These SDK-owned primitives are shared by the CLI and package integrations.
 
@@ -46,11 +46,29 @@ When multiple entries exist, the SDK selects the requested package by key or `na
 
 ## History and merge recovery
 
-History hash capability 3 distinguishes the current canonical writer surface from older epoch-2 writers while retaining readers for epochs 1 and 2. An unsupported epoch is version skew, not permission to reinterpret or silently normalize history.
-
-Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes also carry the current item-hash capability, so a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
-
-Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed.
+History hash capability 3 distinguishes the current canonical writer surface
+from older writers while retaining frozen readers for epochs 1 and 2. Two
+writer surfaces were historically emitted under epoch 2: its earlier form
+excluded linked-test workspace/provenance fields and test-run execution
+receipts while normalizing dependency ids; its later form included those
+fields. Verification recognizes both immutable forms and requires each entry's
+before/after hashes to use one consistent form. Current-document verification
+selects the candidate that matches the verified chain head. An unsupported
+epoch is version skew, not permission to reinterpret or silently normalize
+history.
+
+Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes carry both their schema version and the current item-hash capability, so changing legacy canonicalization invalidates prior verdicts and a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
+
+Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed. SDK gates use `inspectMergeReceiptEvidence` or `runMergeReceiptEvidenceReport` to retain the distinction between no evidence, rejected evidence, and clone-local evidence whose Git directory could not be resolved; `clone_local_evidence_resolved=false` makes the loss-aware report incomplete. Rejected evidence carries bounded privacy-safe source, reason, and receipt-id-or-hash locators, while the exact count and truncation receipt preserve completeness under an agent token budget. Cross-platform ancestor inspection distinguishes an absent receipt store from an unreadable or non-directory root. The list-only and legacy report compatibility projections intentionally return valid receipts only. Diverged history unions also fail closed when deterministic suffix ordering would make any patch operation inapplicable, instead of publishing a rehashed stream with a skipped branch effect.
+
+History receipt summaries are durable references, not cleanup hints. Health
+checks each `context.merge.receipts[].receipt_id` against valid pending and
+reconciled authoritative evidence. A missing reference is returned with its
+item id and one-based history line; unsafe identifiers are SHA-256 locators
+rather than echoed content. Detail is capped at 100 while the exact count and a
+truncation receipt preserve loss awareness. Recovery means restoring the named
+receipt from an authoritative clone or backup. Rewriting append-only history or
+deleting sibling evidence is never an automatic remediation.
 
 ## Strict-create recovery
 

package/docs/MCP_2026_07_28.md

@@ -12,7 +12,9 @@ by [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
 [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
 [pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon). Skills and Apps are tracked
 by [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon) and
-[pm-pznhee](../.agents/pm/features/pm-pznhee.toon).
+[pm-pznhee](../.agents/pm/features/pm-pznhee.toon). Progressive tool discovery
+and canonical model-facing results are tracked by
+[pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
 
 Status: accepted. MCP `2026-07-28` is pm's canonical protocol revision.
 
@@ -39,16 +41,18 @@ capabilities, public cache policy, server identity, and bounded instructions.
 No modern request reads identity, capabilities, or version from a previous
 request.
 
+The optional `dev.unbrained.pm/progressive-tool-discovery` extension is also request-local. Negotiated clients receive a stable five-tool entry catalog and expand it with `pm_discover`; unnegotiated clients retain the complete profile-selected list. Negotiated tool results designate `structuredContent.result` as canonical and use text content only as a pointer, while the isolated compatibility adapter retains duplicated JSON text for existing clients. The public SDK owns ranking, cursor binding, token and omission receipts, and cache invalidation. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 ## Legacy boundary
 
 Legacy means every revision that establishes a session with an `initialize`
 handshake, which the canonical revision defines as `2025-11-25` and earlier.
 The stdio adapter therefore accepts the full initialize-era set, newest first:
 
-| Revision | Accepted at `initialize` | Notes |
-|----------|--------------------------|-------|
-| `2025-11-25` | yes | Final legacy revision; offered when a client omits `protocolVersion` |
-| `2025-06-18` | yes | Earlier legacy revision retained for existing consumers |
+| Revision     | Accepted at `initialize` | Notes                                                                |
+| ------------ | ------------------------ | -------------------------------------------------------------------- |
+| `2025-11-25` | yes                      | Final legacy revision; offered when a client omits `protocolVersion` |
+| `2025-06-18` | yes                      | Earlier legacy revision retained for existing consumers              |
 
 `initialize` answers with the revision the client requested, because a legacy
 client has no fall-forward mechanism and treats the answered version as the

package/docs/MCP_CAPABILITY_SURFACES.md

@@ -1,6 +1,6 @@
 # Runtime capability surfaces
 
-Tracker: [pm-xwah](../.agents/pm/chores/pm-xwah.toon), [pm-kxci8x](../.agents/pm/tasks/pm-kxci8x.toon), [pm-mu8m](../.agents/pm/tasks/pm-mu8m.toon), [pm-9k90](../.agents/pm/features/pm-9k90.toon), [pm-m4ikkz](../.agents/pm/features/pm-m4ikkz.toon), [pm-yf07b7](../.agents/pm/features/pm-yf07b7.toon)
+Tracker: [pm-xwah](../.agents/pm/chores/pm-xwah.toon), [pm-kxci8x](../.agents/pm/tasks/pm-kxci8x.toon), [pm-mu8m](../.agents/pm/tasks/pm-mu8m.toon), [pm-9k90](../.agents/pm/features/pm-9k90.toon), [pm-m4ikkz](../.agents/pm/features/pm-m4ikkz.toon), [pm-yf07b7](../.agents/pm/features/pm-yf07b7.toon), and [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
 
 The SDK exports one agent capability contract for command visibility, MCP tool profiles, resources, and workflow prompts. CLI-facing generators and MCP hosts should project from these contracts instead of maintaining independent allowlists.
 
@@ -15,6 +15,12 @@ Set `PM_MCP_PROFILE` for the `pm-mcp` process:
 
 An activated extension command makes `pm_run` discoverable outside a custom profile. Its action is added to the live `pm_run` action enumeration. Custom profiles remain exact allowlists.
 
+## Progressive discovery
+
+Modern clients may negotiate `dev.unbrained.pm/progressive-tool-discovery`. Their initial `tools/list` response is the stable five-tool entry catalog, and `pm_discover` expands authorized tools by intent, family, and tier under explicit row and token ceilings. Unnegotiated and initialize-era clients retain the full selected profile.
+
+The SDK ranks with visible lexical, semantic, graph, permission, freshness, and usage signals, binds cursors to all ranking inputs, and emits omission recovery plus cache invalidation metadata. Negotiated tool calls make `structuredContent.result` canonical and replace duplicated JSON text with a pointer; compatibility clients retain the old representation. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 Package authors can declare `tier: "core" | "standard" | "full" | "internal"` on `registerCommand()` definitions. The default is `standard`; `internal` commands remain callable by native dispatch but are not advertised by normal MCP profiles.
 
 ## Workspace schema projection