@unbrained/pm-cli 2026.8.8 → 2026.8.10

package/dist/sdk/similarity.js

@@ -5,10 +5,12 @@
  * governance and package-owned duplicate analysis.
  */
 
-!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]="078456b8-ed61-5c47-afc7-7553833934e1")}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]="a2fad90a-3575-5f3e-8cbe-ac380ac45591")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
+import { normalizeStatusInput } from "../core/item/status.js";
+import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import { listAllItemMetadataLight } from "../core/store/item-store.js";
 import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
@@ -62,14 +64,38 @@ async function loadPreparedDuplicateItems(options, since) {
     const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings);
-    const allowedStatuses = options.statuses
-        ? new Set(options.statuses.map((status) => status.trim()).filter(Boolean))
+    const requestedStatuses = options.statuses
+        ?.map((status) => status.trim().toLowerCase())
+        .filter(Boolean);
+    if (options.statuses !== undefined && requestedStatuses?.length === 0) {
+        throw new PmCliError("Duplicate cluster statuses must include at least one lifecycle status or all.", EXIT_CODE.USAGE);
+    }
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const normalizedStatuses = requestedStatuses?.map((status) => {
+        if (status === "all")
+            return status;
+        const normalized = normalizeStatusInput(status, statusRegistry);
+        if (!normalized) {
+            throw new PmCliError(`Unknown duplicate-cluster status "${status}". Allowed: all, ${statusRegistry.definitions.map((entry) => entry.id).join(", ")}.`, EXIT_CODE.USAGE);
+        }
+        return normalized;
+    });
+    const hasAll = normalizedStatuses?.includes("all") === true;
+    if (hasAll && normalizedStatuses?.some((status) => status !== "all")) {
+        throw new PmCliError('The "all" status cannot be combined with other statuses.', EXIT_CODE.USAGE);
+    }
+    const effectiveStatuses = hasAll ? undefined : normalizedStatuses;
+    const allowedStatuses = effectiveStatuses
+        ? new Set(effectiveStatuses)
         : undefined;
-    return (await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema))
-        .filter((item) => (!allowedStatuses || allowedStatuses.has(item.status)) &&
-        (!since || new Date(item.created_at).getTime() >= since.getTime()))
-        .sort((left, right) => left.id.localeCompare(right.id))
-        .map((item) => ({ item, prepared: prepareSimilarityText(item.title) }));
+    return {
+        items: (await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema))
+            .filter((item) => (!allowedStatuses || allowedStatuses.has(item.status)) &&
+            (!since || new Date(item.created_at).getTime() >= since.getTime()))
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map((item) => ({ item, prepared: prepareSimilarityText(item.title) })),
+        statuses: effectiveStatuses,
+    };
 }
 function collectDuplicateCandidatePairs(items, maxPairEvaluations = MAX_BATCH_PAIR_EVALUATIONS) {
     const candidates = new Set();
@@ -233,7 +259,7 @@ export async function findDuplicateClusters(options = {}) {
         limit: undefined,
     });
     const { limit, since } = validateDuplicateClusterOptions(options);
-    const items = await loadPreparedDuplicateItems(options, since);
+    const { items, statuses } = await loadPreparedDuplicateItems(options, since);
     const candidates = collectDuplicateCandidatePairs(items);
     const union = createDuplicateUnionFind(items.length);
     const matches = scoreDuplicateCandidates(items, candidates, threshold, union);
@@ -243,6 +269,10 @@ export async function findDuplicateClusters(options = {}) {
         count: clusters.length,
         threshold,
         source: "metadata_scan",
+        filters: {
+            statuses: statuses ?? null,
+            since: options.since ?? null,
+        },
         cost: {
             item_count: items.length,
             candidate_pairs: candidates.size,
@@ -273,4 +303,4 @@ export async function evaluateSimilarityGovernance(candidate, options) {
     return { mode: options.mode, bypassed, result };
 }
 //# sourceMappingURL=similarity.js.map
-//# debugId=078456b8-ed61-5c47-afc7-7553833934e1
+//# debugId=a2fad90a-3575-5f3e-8cbe-ac380ac45591

package/dist/sdk/structured-mutations.js

@@ -5,7 +5,7 @@
  * transaction contract and normalizes full item documents for CLI round trips.
  */
 
-!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]="91be2c5d-c495-54bc-ac79-b4c645ad2c6e")}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]="07876c03-63a8-5c69-9c6c-c3446076a382")}catch(e){}}();
 import crypto from "node:crypto";
 import { normalizeItemId, normalizePrefix } from "../core/item/id.js";
 import { EXIT_CODE, ITEM_PROJECT_CONTEXT_KEYS, } from "../core/shared/constants.js";
@@ -43,6 +43,9 @@ const READ_ONLY_ITEM_KEYS = new Set([
     "format_version",
     "path",
     "author",
+    "collection_counts",
+    "notes_count",
+    "tests_count",
 ]);
 const UPDATE_READ_ONLY_ITEM_KEYS = new Set([
     ...READ_ONLY_ITEM_KEYS,
@@ -568,4 +571,4 @@ export function validateItemMutationRows(value) {
     return parseItemMutationBatch(JSON.stringify(value));
 }
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=91be2c5d-c495-54bc-ac79-b4c645ad2c6e
+//# debugId=07876c03-63a8-5c69-9c6c-c3446076a382

package/dist/sdk/test/linked-command-detection.d.ts

@@ -1,8 +1,3 @@
-/**
- * @module sdk/test/linked-command-detection
- *
- * Parses linked-test command invocations for sandbox and context-safety checks.
- */
 /** Public contract for pm global flags with value, shared by SDK and presentation-layer consumers. */
 export declare const PM_GLOBAL_FLAGS_WITH_VALUE: Set<string>;
 /** Value-bearing flags accepted before item positionals by item-referencing commands. */
@@ -28,7 +23,7 @@ export declare const SCRIPT_RUN_FLAGS_WITH_VALUE: Set<string>;
 /** Implements split normalized command segments for the public runtime surface of this module. */
 export declare function splitNormalizedCommandSegments(normalizedCommand: string): string[];
 /** Extract pm CLI arguments from one normalized shell-command segment. */
-export declare function extractPmInvocationArgsFromSegment(segment: string): string[] | null;
+export declare function extractPmInvocationArgsFromSegment(segment: string, cwd?: string): string[] | null;
 /** Extract referenced item IDs from pm CLI invocations embedded in one command. */
 export declare const extractReferencedPmItemIdsFromCommand: (command: string, idPrefix?: string) => string[];
 /** Implements strip leading env assignments for the public runtime surface of this module. */
@@ -42,7 +37,7 @@ export declare function normalizePackageSpecifier(token: string): string;
 /** Implements check whether pm cli package token for the public runtime surface of this module. */
 export declare function isPmCliPackageToken(token: string): boolean;
 /** Implements check whether pm cli script token for the public runtime surface of this module. */
-export declare function isPmCliScriptToken(token: string): boolean;
+export declare function isPmCliScriptToken(token: string, cwd?: string): boolean;
 /** Implements parse npx command for the public runtime surface of this module. */
 export declare function parseNpxCommand(tokens: string[]): {
     command: string;

package/dist/sdk/test/linked-command-detection.js

@@ -9,7 +9,9 @@
 // normalized command string. Kept in core so SDK governance and CLI test
 // execution share one dependency-direction-safe parser.
 
-!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]="8c4d45cf-6b97-5151-a325-db09d31962a7")}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]="673a5a26-6214-58d6-af19-baee5a8359f0")}catch(e){}}();
+import { readFileSync } from "node:fs";
+import path from "node:path";
 const PM_SUBCOMMANDS_WITH_ITEM_REFERENCE = new Set([
     "get",
     "history",
@@ -277,15 +279,15 @@ export function splitNormalizedCommandSegments(normalizedCommand) {
         .filter((segment) => segment.length > 0);
 }
 /** Extract pm CLI arguments from one normalized shell-command segment. */
-export function extractPmInvocationArgsFromSegment(segment) {
+export function extractPmInvocationArgsFromSegment(segment, cwd = process.cwd()) {
     const tokens = stripLeadingEnvAssignments(segment.split(" ").filter((token) => token.length > 0));
     if (tokens.length === 0)
         return null;
     const [executable, ...args] = tokens;
-    if (isPmExecutableToken(executable) || isPmCliScriptToken(executable)) {
+    if (isPmExecutableToken(executable) || isPmCliScriptToken(executable, cwd)) {
         return args;
     }
-    if (executable === "node" && args[0] && isPmCliScriptToken(args[0])) {
+    if (executable === "node" && args[0] && isPmCliScriptToken(args[0], cwd)) {
         return args.slice(1);
     }
     const invocation = executable === "npx" || executable === "bunx"
@@ -408,10 +410,21 @@ export function isPmCliPackageToken(token) {
         token.endsWith("/pm-cli"));
 }
 /** Implements check whether pm cli script token for the public runtime surface of this module. */
-export function isPmCliScriptToken(token) {
-    return (token === "dist/cli.js" ||
-        token === "./dist/cli.js" ||
-        token.endsWith("/dist/cli.js"));
+export function isPmCliScriptToken(token, cwd = process.cwd()) {
+    const normalized = token.replaceAll("\\", "/");
+    if (normalized !== "dist/cli.js" &&
+        normalized !== "./dist/cli.js" &&
+        !normalized.endsWith("/dist/cli.js")) {
+        return false;
+    }
+    const scriptPath = path.resolve(cwd, token);
+    try {
+        const packageJson = JSON.parse(readFileSync(path.join(path.dirname(path.dirname(scriptPath)), "package.json"), "utf8"));
+        return packageJson.name === "@unbrained/pm-cli";
+    }
+    catch {
+        return false;
+    }
 }
 /** Implements parse npx command for the public runtime surface of this module. */
 export function parseNpxCommand(tokens) {
@@ -531,4 +544,4 @@ export function firstPositionalToken(tokens, flagsWithValue = new Set()) {
     return undefined;
 }
 //# sourceMappingURL=linked-command-detection.js.map
-//# debugId=8c4d45cf-6b97-5151-a325-db09d31962a7
+//# debugId=673a5a26-6214-58d6-af19-baee5a8359f0

package/dist/sdk/workspace-snapshot.d.ts

@@ -19,10 +19,14 @@ declare class WorkspaceLockHeartbeat {
     constructor(lockPath: string, owner: string, ttlSeconds: number);
     /** Begin renewing the lock without keeping the process alive on its own. */
     start(): void;
+    /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
+    refreshNow(): Promise<void>;
     /** Fail the restore before activation when lease ownership was lost. */
     assertHealthy(): void;
     /** Stop future renewals and await the last in-flight atomic write. */
     stop(): Promise<void>;
+    /** Serialize renewal attempts and retain the first ownership failure. */
+    private scheduleRenewal;
     /** Atomically refresh only the lock still owned by this process and actor. */
     private renew;
 }

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!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]="cdde844a-a14a-501d-a45b-18cbd1dd9008")}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]="470bb466-4619-5c54-a154-186b7ef4a049")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -55,19 +55,18 @@ class WorkspaceLockHeartbeat {
     }
     /** Begin renewing the lock without keeping the process alive on its own. */
     start() {
+        this.scheduleRenewal();
         this.timer = setInterval(() => {
-            if (this.refresh !== undefined)
-                return;
-            this.refresh = this.renew()
-                .catch((error) => {
-                this.failure = error;
-            })
-                .finally(() => {
-                this.refresh = undefined;
-            });
+            this.scheduleRenewal();
         }, this.intervalMs);
         this.timer.unref();
     }
+    /** Force and await one owned renewal so callers can establish a fresh lease boundary. */
+    async refreshNow() {
+        this.scheduleRenewal();
+        await this.refresh;
+        this.assertHealthy();
+    }
     /** Fail the restore before activation when lease ownership was lost. */
     assertHealthy() {
         if (this.failure !== undefined) {
@@ -83,6 +82,18 @@ class WorkspaceLockHeartbeat {
         await this.refresh;
         this.assertHealthy();
     }
+    /** Serialize renewal attempts and retain the first ownership failure. */
+    scheduleRenewal() {
+        if (this.refresh !== undefined || this.failure !== undefined)
+            return;
+        this.refresh = this.renew()
+            .catch((error) => {
+            this.failure = error;
+        })
+            .finally(() => {
+            this.refresh = undefined;
+        });
+    }
     /** Atomically refresh only the lock still owned by this process and actor. */
     async renew() {
         const parsed = JSON.parse(await readFile(this.lockPath, "utf8"));
@@ -483,6 +494,7 @@ export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, optio
     const releaseWorkspaceLock = await acquireLock(pmRoot, WORKSPACE_WRITER_LOCK_ID, lockTtlSeconds, author, false, false, lockWaitMs);
     const heartbeat = new WorkspaceLockHeartbeat(getLockPath(pmRoot, WORKSPACE_WRITER_LOCK_ID), author, lockTtlSeconds);
     heartbeat.start();
+    await heartbeat.refreshNow();
     let staging;
     let swapStarted = false;
     let heartbeatStopped = false;
@@ -536,6 +548,7 @@ export async function restoreWorkspaceSnapshotWithRecovery(pmRoot, target, optio
         await swapWorkspaceSnapshotRootWithActivation(staging, pmRoot, backup, DEFAULT_ATOMIC_OPERATIONS, async () => {
             heartbeat.start();
             heartbeatStopped = false;
+            await heartbeat.refreshNow();
         });
         await heartbeat.stop();
         heartbeatStopped = true;
@@ -596,4 +609,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=cdde844a-a14a-501d-a45b-18cbd1dd9008
+//# debugId=470bb466-4619-5c54-a154-186b7ef4a049

package/docs/AGENT_GUIDE.md

@@ -50,7 +50,9 @@ Repeated singular/plural list flags accumulate, so `--tag a --tag b` is equivale
 
 `--tags` REPLACES the whole tag list. To edit tags without restating the full set, prefer `--add-tags <value>` (adds without replacing) and `--remove-tags <value>` (prunes) on `create`/`update`/`update-many` (both repeatable; CSV or JSON-array). `--remove-tags` is `update`/`update-many` only. Also note `--expected`/`--actual` are short aliases for `--expected-result`/`--actual-result` on these commands, matching `pm close`.
 
-`--acceptance-criteria`/`--ac` likewise REPLACES the whole criteria value. Prefer `--add-ac <text>` (appends one criterion; deduped on exact text) and `--remove-ac <text>` (removes one criterion by exact text; unmatched selectors surface a `remove_ac_unmatched` warning) on `update`/`update-many` so concurrent branch edits with disjoint additions merge instead of clobbering. Acceptance criteria use semicolons as storage boundaries, so one criterion cannot itself contain a semicolon.
+`--acceptance-criteria`/`--ac` likewise explicitly REPLACES the whole criteria value and cannot be combined with `--add-ac` or `--remove-ac`. Prefer `--add-ac <text>` (appends one criterion; deduped on exact text) and `--remove-ac <text>` (removes one criterion by exact text) on `update`/`update-many` so concurrent branch edits with disjoint additions merge instead of clobbering. Every removal must match or the complete mutation fails atomically with structured unmatched-selector recovery. Acceptance criteria use semicolons as storage boundaries, so one criterion cannot itself contain a semicolon.
+
+Local dependency targets supplied to `create`, `update`, or `update-many` must already exist. Mark cross-workspace targets with `source_kind=external`; reserve `--allow-unresolved-deps` for deliberate staged imports and retain its structured warning as evidence.
 
 ```bash
 pm update <item-id> --add-tags urgent,backend   # keep existing tags, add two
@@ -189,6 +191,7 @@ Use these defaults unless the task requires otherwise:
 - `pm validate --check-resolution --check-history-drift` before closing broad work.
 - `pm history-redact <id> --dry-run` before rewriting sensitive history payloads, then rerun without `--dry-run` once scope is confirmed.
 - `pm history-repair <id> --dry-run` when `pm health` or `pm validate --check-history-drift` report drifted streams; it re-anchors the hash chain and reconciles with the on-disk item without touching item content. Rerun without `--dry-run` to apply.
+- `pm merge reconcile --dry-run --json` after a branch merge that touched tracker data. Review every discarded-value receipt before applying; a lossy reconciliation requires the explicit `--force` acceptance flag. `history-repair` alone does not settle merge receipts.
 - `pm schema list` and `pm schema show <Type>` before creating custom-domain work; they show built-in, persisted custom, and extension-provided item types without reading schema files by hand.
 - `pm schema add-type <Name>` when `pm create`/`pm update` reject a project-specific type as invalid; it registers the type in `.agents/pm/schema/types.json` so `pm create <Name> "..."` works. Built-in types are reserved; the upsert is idempotent. `pm schema remove-type <Name>` removes a custom type (warns, non-blocking, if items still use it).
 - `pm schema add-status <id> --role <role>` / `pm schema remove-status <id>` manage custom lifecycle statuses in `.agents/pm/schema/statuses.json`; roles come from the runtime status-role vocabulary, the upsert is idempotent, and built-in default statuses cannot be removed. `pm schema list` now reports statuses (builtin vs custom) alongside types.
@@ -204,7 +207,7 @@ Use these defaults unless the task requires otherwise:
 Concurrent agents work on ordinary Git branches/worktrees; tracker artifacts need the semantic merge contract from [Merge Safety](MERGE_SAFETY.md). The short loop:
 
 - After a fresh clone or new worktree, run `pm merge install` once so the field-aware merge drivers back the committed `.gitattributes` fence.
-- After every merge that touches `.agents/pm`, run `pm validate --check-storage-integrity` and `pm history --verify --strict-exit`; follow the remediation output (`pm history-repair` wiring included).
+- After every merge that touches `.agents/pm`, run `pm merge reconcile --dry-run --json`, review the receipt classification, then apply `pm merge reconcile`. Add `--force` only after explicitly accepting or re-applying every discarded scalar value. Finish with `pm validate --check-storage-integrity` and `pm history --verify --strict-exit`.
 - Repositories fanning out many branches between merges should raise id entropy: `pm config project set ids_token_length 6`.
 - Use `--add-ac`/`--remove-ac` (not `--ac`) so concurrent acceptance-criteria edits merge instead of clobbering.
 

package/docs/COMMANDS.md

@@ -2,7 +2,7 @@
 
 This is a task-oriented command guide. For exact flags, use runtime help because extensions and settings can change the active surface:
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), and the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
 ```bash
 pm <command> --help
@@ -78,6 +78,7 @@ Use `--with-packages` for one-step agent setup when bundled package commands sho
 pm package                     # bare command defaults to --explore (list installed)
 pm install '*' --project
 pm package catalog --project
+pm package manage --project --output-format json
 pm install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
@@ -90,6 +91,11 @@ pm upgrade --cli-only --repair
 ```
 
 `pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+`pm package catalog` emits one row per package, with every resolvable bundled
+alias preserved in `aliases`; totals therefore measure packages rather than
+alias-index entries. `pm package manage` participates in the universal read
+output contract, so `--output-include`, `--output-limit`, `--output-budget`, and
+`--output-format` behave like the same controls on other SDK-backed reads.
 Install output includes a light `verification` summary with target tracker root, activation state, registered commands/actions/item types, and an `ok|degraded` health verdict. Runtime activation failure sets the command result and process exit status to failure; inspect `activation_diagnostics` and `command_discovery.next_steps` for the exact recovery path.
 Bare install names use bundled aliases before installed npm packages. Every
 install result reports `source_resolution`; when both candidates exist it marks
@@ -113,6 +119,7 @@ pm list-open --type Task --priority 1 --limit 20
 pm list-in-progress --limit 20
 pm aggregate --group-by parent,type --status open
 pm aggregate --group-by parent,type --completion --include-unparented
+pm duplicates --status all --threshold 0.8
 ```
 
 Use `pm next` when the only question is "what should I work on now?" It computes dependency-aware readiness, keeps dangling dependency ids blocked until repaired, and combines lifecycle-blocked plus graph-blocked work in the companion queue. The `recommended` projection is excluded from the `ready` tail; every actionable row carries its one-based `rank`, and the tail preserves the exact recommendation order. Foreign-owned in-progress work is summarized under `held_by_others`. Human-gated `Decision` records remain visible under `decision_needed` but are excluded from agent recommendations by default.
@@ -126,6 +133,10 @@ pm next --ready-only --limit 3 --json   # tightest agent-loop projection
 ```
 
 Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
+Use `duplicates --status all` for a true whole-history duplicate check. The
+result echoes `filters.statuses: null` for the unrestricted corpus; named or
+custom statuses are normalized through the runtime status registry and an
+unknown status fails instead of returning a false-clean result.
 Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
 Add `--at <version|ISO-timestamp>` for a verified point-in-time read. It replays the same hash-checked history kernel used by restore but never acquires a lock, writes the item, or appends history. The result always includes `reconstructed: true`, `as_of_version`, and `as_of_timestamp`. Future/out-of-range targets fail with structured `valid_range` metadata. `--at` cannot be combined with `--tree`; workspace-wide historical graph projections require a future indexed primitive.
@@ -347,7 +358,9 @@ pm close-many --rollback close-many-20260604-abc123   # restore the batch
 
 `close-many` skips already-terminal matches by default (pass `--force` to re-close), accepts `--completed-at <timestamp>` to preserve one shared actual-completion time across the batch, reports a per-item plan (`close`/`skip`, plus `active_child_ids` for parents that would be orphaned) under `--dry-run`, and writes a checkpoint by default (`--no-checkpoint` to disable). Checkpoints for both commands live under `.agents/pm/checkpoints/<command>/` and are restored with `--rollback <checkpoint-id>`.
 
-When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`).
+When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`). Unknown-command guidance ranks agent verb synonyms first, bounded edit distance second, and substring matches last; `pm log` therefore points to `history`, `comments`, and `notes`, never a `catalog` command.
+
+Commands addressed to one item retain their canonical positional form and also accept `--id <item-id>` consistently. For example, `pm get --id pm-a1`, `pm comments --id pm-a1 --add "..."`, and `pm test --id pm-a1 --run` are equivalent to their positional forms. Supplying both forms is a usage error. Command-scoped `pm contracts --flags-only`, completion, and help expose the same alias.
 
 ## Create and Update
 
@@ -368,6 +381,7 @@ pm create "Fix login bug" --type Issue --priority high
 `pm create` defaults `--type` to `settings.governance.create_default_type` (falling back to `Task`).
 Set it with `pm config project set governance-create-default-type <Type>` (must resolve to a known item type).
 Pass `--create-mode strict` to require an explicit `--type` flag for governance-controlled flows.
+Type-aware help reports requirements for the selected mode and lists stricter requirements separately. A strict required repeatable collection can be deliberately empty: for example, `--clear-deps` satisfies a required dependency consideration while writing no relationship edge and recording `explicit_unset=dependencies` in history. Required runtime-schema fields are named with their metadata key and expected input format in structured recovery.
 `pm update --status` can be constrained per item type via `schema.type_workflows` plus
 `pm config project set governance-workflow-enforcement <off|warn|strict>` (see CONFIGURATION.md → Per-Type Workflows).
 Priority accepts either `0..4` or the equivalent names `critical`, `high`, `medium`, `low`, and `minimal`.
@@ -439,7 +453,7 @@ pm update pm-abc1 --remove-tags stale            # drops "stale", keeps the rest
 pm create "New backend task" --add-tags backend,p1
 ```
 
-Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` REPLACES the whole value, while `--add-ac <text>` appends one criterion (repeatable; deduped on exact text) and `--remove-ac <text>` removes one criterion by exact text match (repeatable; a non-matching selector adds a `remove_ac_unmatched:<text>` warning instead of silently no-oping). Criteria are stored with semicolon-space separators, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
+Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` explicitly REPLACES the whole value and returns an `acceptance_criteria_replaced:<before-count>:<after-count>` warning when it changes existing criteria. `--add-ac <text>` appends one criterion (repeatable; deduped on exact text), while `--remove-ac <text>` removes one criterion by exact text match. Every requested removal must match: otherwise the mutation fails atomically with `acceptance_criteria_remove_unmatched` and reports the unmatched selectors, without applying valid removals or additions. Whole-value replacement cannot be combined with additive flags in one mutation. Criteria are stored with semicolon-space separators, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
 
 ```bash
 pm update pm-abc1 --add-ac "error path covered by a regression test"
@@ -478,7 +492,7 @@ pm update <id> \
 pm update <id> --expected "Retry succeeds after backoff" --actual "Retry threw on first attempt"
 ```
 
-Repeat `--ac`/`--acceptance-criteria` to build multi-part criteria; values are stored in order joined by `; `. Dependency inputs accept either a bare existing item id or the explicit `id=<id>,kind=<kind>` form, and malformed shorthand such as `related:pm-abcd` fails before it can create a dangling graph edge.
+Repeat `--ac`/`--acceptance-criteria` to build multi-part criteria; values are stored in order joined by `; `. Dependency inputs accept either a bare existing item id or the explicit `id=<id>,kind=<kind>` form, and malformed shorthand such as `related:pm-abcd` fails before it can create a dangling graph edge. New local dependency targets must already exist. Cross-workspace targets must declare `source_kind=external` (canonicalized to `global`); deliberately staged local edges require `--allow-unresolved-deps` and return one structured `dependency_target_unresolved:<id>` warning per missing target. The same validation runs during `update-many --dry-run`, so preview and apply cannot disagree.
 
 Mutation commands (`create`/`update`/`close`/`append`/...) default to an
 agent-efficient `id`/`status`/`changed_field_count` envelope. Use
@@ -736,7 +750,7 @@ pm test <id> --run --only-last
 pm test-all --status in_progress --progress
 ```
 
-Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` for repo-local test suites; normal package-manager scripts such as `pnpm test` and `npm run test` are accepted because linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH`. Direct runner binaries such as `vitest` or `node --test` still need the wrapper or explicit inline sandbox env. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
+Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` for repo-local test suites; normal package-manager scripts such as `pnpm test` and `npm run test` are accepted because linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH`. Direct runner binaries such as `vitest` or `node --test` still need the wrapper or explicit inline sandbox env. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. Linked tests retain append order; consequently `--only-last` always selects the most recently added stored test. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
 
 Strict linked-test guards:
 
@@ -891,12 +905,19 @@ one-command reconciliation gate:
 ```bash
 pm merge reconcile --dry-run --json
 pm merge reconcile --message "Reconcile branch histories" --json
+# Only after reviewing every discarded-value receipt:
+pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The command scans every history stream, delegates repairs to the audited
 `history-repair --all` engine, then runs the history-drift and storage-integrity
 validation checks. Dry-run leaves drift intact and reports it in `validation`;
-apply exits nonzero if any stream fails or either invariant stays red. No Git
+apply exits nonzero if any stream fails or either invariant stays red. Lossless
+receipts remain visible in `pm merge report` but do not count as discarded-value
+decisions. When a receipt contains a discarded scalar value, apply refuses with
+`merge_reconcile_discards_require_acceptance` until the coordinator reviews or
+re-applies the value and passes `--force`. `pm history-repair` is the narrower
+drift-only tool and never substitutes for receipt reconciliation. No Git
 hook is installed automatically—teams may call this command from an explicit
 post-merge hook after opting into that policy.
 

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -0,0 +1,29 @@
+# Dependency-kind contract
+
+Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon)
+
+Dependency rows have one canonical stored spelling per relationship meaning. Command inputs remain compatibility-friendly: hyphens normalize to underscores and the aliases below are accepted, but `pm create` and `pm update` persist the canonical kind. Existing historical rows are never rewritten implicitly.
+
+| Canonical kind | Accepted legacy aliases |
+| --- | --- |
+| `blocked_by` | `depends_on`, `depends-on` |
+| `related` | `related_to`, `related-to` |
+| `parent` | `child_of`, `child-of`, `epic` |
+| `child` | `parent_child`, `parent-child`, `task` |
+
+`epic` and `task` are compatibility aliases, not item types embedded in the relationship ontology. New integrations should use `parent` or `child` and express the work classification through the item `type` field.
+
+The SDK relationship registry is authoritative. `canonicalizeRelationshipKind()` rejects unknown spellings, while `resolveCanonicalRelationshipKind()` supports validation flows that need an undefined result. `pm contracts` publishes `relationship_kind_contracts` with canonical names, aliases, inverses, and ordering/hierarchy semantics.
+
+## Direction and actionability
+
+`blocked_by` and `blocks` are inverse storage directions with identical scheduling meaning:
+
+- `A --blocked_by--> B` means A waits for B.
+- `B --blocks--> A` means A waits for B.
+
+Readiness, `pm next`, context blocker summaries, `pm list-blocked`, downstream `unblocks` projections, and close-time auto-unblock use that shared interpretation. This applies to mixed-direction corpora without migrating existing rows.
+
+## Legacy observability
+
+`pm deps` returns `legacy_alias_counts` for the workspace. `pm graph audit` returns the same field beside the canonical `profile.edges_by_kind` counts. Empty objects mean no stored alias debt. These diagnostics are read-only; terminal history remains untouched until an explicitly governed migration is requested.

package/docs/ITEM_READ_PROJECTIONS.md

@@ -0,0 +1,26 @@
+# Stable Item Read Projections
+
+Tracker reference: [pm-b1w8vr](../.agents/pm/issues/pm-b1w8vr.toon).
+
+Item mutation and read-back surfaces share one collection vocabulary:
+`comments`, `notes`, `learnings`, `files`, `tests`, `docs`, `reminders`, and
+`events`. Every normal `pm get` and SDK `runGet` result carries
+`item.collection_counts` with all eight keys, including zero values. This gives
+agents a stable, low-token way to verify a write without requesting complete
+collection payloads.
+
+`brief` and `standard` omit the collection arrays but retain the stable counts.
+`deep`, `full`, and `--full` include every collection array, normalizing absent
+collections to `[]`, and retain `notes_count`, `tests_count`, and
+`collection_counts`. A full projection is therefore a structural superset of
+the standard item projection rather than a different shape.
+
+Field projections can request `collection_counts` directly:
+
+```bash
+pm get pm-example --fields id,updated_at,collection_counts
+```
+
+Package authors receive the same contract from `runGet`. Do not infer whether
+a collection exists by checking for an omitted key; use the count projection,
+or request a full projection when the entries themselves are needed.

package/docs/MERGE_SAFETY.md

@@ -1,6 +1,6 @@
 # Multi-Branch Tracker Merge Safety
 
-Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
+Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
@@ -56,20 +56,22 @@ pm merge install --dry-run --json
 
 | Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                          |
 | ---------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; format-specific drivers avoid passing the repository path through Git's shell command, append-like collections use set union, `updated_at` uses latest timestamp, and canonical serialization recomputes TOON counts.            |
+| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; append-like collections use set union, `updated_at` uses latest timestamp, scalar conflicts select a stable direction-independent value, and canonical serialization recomputes TOON counts.                                     |
 | `history/*.jsonl`                                                | `pm-history`                        | Preserves the common prefix and both divergent suffixes, orders deterministically, then re-anchors the resulting hash chain.                                                                                                                            |
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
 
-When both sides change the same scalar or JSON leaf differently, the driver writes a parseable preferred-side result but exits nonzero. Git keeps the path conflicted so a human or coordinating agent must review the losing value and explicitly `git add` the resolution. Use `--prefer theirs` only when that is the intended resolution policy.
+When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution.
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
 
-For item conflicts, the driver also writes a clone-local receipt below the Git
-directory. It contains retained and discarded values so recovery does not
-depend on a reflog. Raw values never enter public tracker history:
-reconciliation records field names and value hashes, while the explicit local
-report is the only command that shows recoverable values:
+For item conflicts, the driver writes a clone-local receipt below the Git
+directory and a durable privacy-safe sidecar below `merge-receipts/` in the
+tracker. The local receipt contains retained and discarded values so recovery
+does not depend on a reflog. The tracked sidecar contains only field names and
+value hashes, so fresh clones and CI can still fail closed on an unreviewed
+decision without publishing either value. When both copies exist the SDK
+deduplicates them and prefers the locally recoverable copy:
 
 ```bash
 pm merge report
@@ -97,9 +99,16 @@ After every branch merge that touches `.agents/pm`, run:
 ```bash
 pm merge reconcile --dry-run --json
 pm merge reconcile --message "Reconcile merged tracker histories" --json
+# Required only after every discarded field has been reviewed or re-applied:
+pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The preview reports every drifted stream and pending receipt without mutation.
+Lossless receipts are reported as provenance but do not become blocking merge
+decisions. Receipts with discarded scalar values remain blocking and the apply
+pass refuses them unless the coordinator explicitly supplies `--force` after
+review. This prevents a routine history repair from silently accepting data
+loss while preserving a zero-noise path for merges that retained both changes.
 It exits nonzero while either merge-critical validation check is non-green, so
 CI and explicit post-merge hooks cannot approve unresolved receipts or drift.
 The apply pass uses the audited history rewrite boundary to append a

package/docs/README.md

@@ -46,17 +46,14 @@ pm guide release --json
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [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 Truth Contracts](SDK_CONTEXT_TRUTH_CONTRACTS.md) - typed tracker-root diagnostics and explicit merge-driver enforcement policy.
+- [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
 - [Self-Describing Context Contracts](SELF_DESCRIBING_CONTEXT_CONTRACTS.md) - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [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 Context Coordination](SDK_CONTEXT_COORDINATION.md) - durable mutation events, bounded duplicate governance, and scale-safe package primitives.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
-- [SDK Context Integrity Primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) - batch duplicate discovery, structured errors, Plan evidence/lifecycle, sparse settings, tombstones, linked-test output, relocation diagnostics, and scoped output services.
-- [SDK Context Integrity](SDK_CONTEXT_INTEGRITY.md) - truthful `get` projections, bounded annotation mutations, shared author coordinates, health provider boundaries, and changeset-aware replication gates.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
@@ -80,7 +77,7 @@ pm guide release --json
 | `quickstart`              | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md)                                       |
 | `commands`                | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md)                                 |
 | `workflows`               | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md)                                                |
-| `sdk`                     | [SDK](SDK.md), [Architecture](ARCHITECTURE.md)                                                      |
+| `sdk`                     | [SDK](SDK.md), [SDK context contracts](SDK_CONTEXT.md), [Architecture](ARCHITECTURE.md)             |
 | `extensions`, `packages`  | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
 | `skills`                  | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*`                                               |
 | `harnesses`               | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md`                        |