@unbrained/pm-cli 2026.8.8 → 2026.8.9

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/docs/AGENT_GUIDE.md

@@ -189,6 +189,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 +205,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

@@ -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.
@@ -891,12 +902,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,12 +56,12 @@ 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).
 
@@ -97,9 +97,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/RELATIONSHIP_GRAPH.md

@@ -16,7 +16,7 @@ Ordering-cycle validation considers only kinds whose registry definition sets `o
 
 SDK queries are deterministic, bounded, cancellation-aware, and return explicit visited-node, inspected-edge, truncation, and continuation metadata. The graph kernel supplies adjacency, incoming and outgoing traversal, closure, shortest path, reverse impact through incoming traversal, and induced subgraphs. The in-memory index is rebuildable directly from item metadata; durable large-workspace indexes remain an interchangeable storage implementation.
 
-Ordering kinds also declare precedence. `source_before_target` means the source must execute first; `target_before_source` models dependency-shaped edges such as `blocked_by`. Custom kinds default to source-first for compatibility, but domain packages should declare the direction explicitly. Analytics consume this field and never infer execution meaning from the label.
+Ordering kinds also declare precedence. `source_before_target` means the source must execute first; `target_before_source` models dependency-shaped edges such as `blocked_by`. Custom kinds default to source-first for compatibility, but domain packages should declare the direction explicitly. Analytics consume this field and never infer execution meaning from the label. Built-in canonical spellings, compatibility aliases, and inverse actionability are defined in [Dependency-kind contract](DEPENDENCY_KIND_CONTRACT.md).
 
 Hierarchy kinds likewise declare which endpoint is the structural parent. `source_parent` supports domain edges such as company `owns` asset, while `target_parent` preserves item-shaped child `parent` parent storage. Custom hierarchy kinds default to `source_parent`; packages should declare the orientation explicitly when their persisted edge shape differs. Context explanations use this contract instead of inferring ancestry from a kind name.
 

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -2,7 +2,10 @@
 
 Tracker references: [pm-9wbiye](../.agents/pm/issues/pm-9wbiye.toon),
 [pm-rbg1qo](../.agents/pm/issues/pm-rbg1qo.toon), and
-[pm-oqo9l2](../.agents/pm/features/pm-oqo9l2.toon).
+[pm-oqo9l2](../.agents/pm/features/pm-oqo9l2.toon),
+[pm-3zgh2c](../.agents/pm/features/pm-3zgh2c.toon),
+[pm-eq9dlw](../.agents/pm/issues/pm-eq9dlw.toon), and
+[pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon).
 
 Project management is context management. The public SDK therefore carries a
 session's purpose and episode boundary through the same immutable history that
@@ -59,7 +62,7 @@ import { spawn } from "node:child_process";
 import { agentSessionEnvironment } from "@unbrained/pm-cli/sdk";
 
 const session = {
-  provenance: { role: "grader", topic: "package acceptance" },
+  provenance: { role: "release-operator", topic: "package acceptance" },
   episode: { id: "package-acceptance", label: "Package acceptance" },
 };
 
@@ -75,6 +78,36 @@ The environment contract is `PM_AGENT_SESSION_ROLE`,
 context keys, distinct from intentional per-observation overrides such as
 `PM_AGENT_MODEL`.
 
+Roles use the controlled values `implementer`, `implementation`,
+`investigator`, `orchestrator`, `planner`, `release-operator`, and `reviewer`.
+Case, spaces, and underscores normalize to lowercase hyphenated values. Other
+values are ignored instead of polluting analytics. Presence-only harness flags,
+including `CLAUDE_CODE_CHILD_SESSION=1`, are detection evidence and are never
+persisted as semantic roles.
+
+For ordinary CLI mutations, the detector can infer an `implementer` or
+`reviewer` role from the bounded command verb and a topic from an explicit
+`pm-...` item argument. Explicit overrides, session declarations, and trusted
+host declarations retain precedence over this inference.
+
+## Diagnose missing provenance
+
+`diagnoseAgentIdentity()` is the additive diagnostic companion to
+`detectAgentIdentity()`. It returns the same privacy-safe identity plus a
+`provenance_outcomes` row for every built-in dimension. Each row is
+`resolved`, `unavailable`, or `failed`, carries rule version `v1`, and may name
+the bounded built-in resolver. It never contains environment values, session
+paths, prompts, or file contents.
+
+New mutation history records failed resolver outcomes under
+`context.agent_provenance_outcomes`; ordinary unavailable dimensions retain
+the compact legacy-compatible null projection. A resolver is only counted as
+attempted when its required input exists. Consequently `pm health` can report
+`provenance_resolver_zero_success:<harness>:<dimension>:<resolver>:<attempts>`
+without confusing an unavailable harness signal with a failed resolver. The
+warning is advisory and the storage check includes the bounded attempt and
+success counters for diagnosis.
+
 ## Cross an MCP boundary
 
 An embedding MCP client can add bounded `provenance` and `episode` fields to

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), and [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), and [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon).
 
 ## Agent Quick Context
 
@@ -18,6 +18,13 @@ pm get pm-a1b2 --output-include item,claim_state
 
 An unknown selector is a usage refusal that lists the valid vocabulary. Selecting the complete `item` object together with an item field is also refused because the two selectors express conflicting projection depths. Every successful projection carries an `omission_receipt` with the exact selectors needed to restore withheld item fields or sections.
 
+Standard and brief item reads expose the stable `collection_counts` selector;
+full reads retain those counts and normalize every supported collection key to
+an array. `--output-include item.collection_counts` therefore uses the same
+selector grammar and omission receipts as any other SDK-owned item field.
+
+The same SDK-owned read-output registry now declares `package manage` as a first-class read surface. Package authors can resolve either `package manage` or `package-manage` to its canonical contract and discover the universal include, amount, cost, and encoding dimensions without copying CLI knowledge.
+
 ## Bounded annotation mutations
 
 Adding, editing, or deleting a comment, note, or learning returns the changed entry plus mutation and omission receipts. The reply size therefore stays independent of the item’s existing annotation history. Pass `--full-history` when a human or integration genuinely needs the complete post-mutation collection:
@@ -48,6 +55,14 @@ The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAu
 
 `pm health` is read-only by default and never refreshes embeddings merely because a semantic provider is configured. Provider I/O requires `--refresh-vectors`; `--skip-vectors` or `--no-refresh` records the explicit non-provider path. Provider requests remain bounded by the configured embedding timeout, and a failed refresh reports the responsible vector diagnostic plus the skip remediation.
 
+Storage integrity is evaluated independently of that provider boundary. Lossless merge receipts remain visible as provenance, while only receipts containing discarded scalar values produce `merge_decisions_unreviewed` guidance; neither classification enables vector refresh or remote provider I/O.
+
+The storage check also reads at most 10,000 local immutable events for bounded
+agent-provenance resolver outcomes. This scan performs no network or provider
+I/O, tolerates malformed streams already owned by integrity diagnostics, and
+reports an advisory warning only when a resolver was actually attempted but
+never succeeded.
+
 ## Replication and refusal gate
 
 `scripts/release/surface-replication-sets.json` declares replicated SDK, CLI, MCP, documentation, and test members. `pnpm quality:surface-replication` activates sets from the Git changeset, verifies every member invariant, and reports:

package/docs/SENTRY_CONTRACT_EPOCHS.md

@@ -0,0 +1,20 @@
+# Sentry Error Contract Epochs
+
+Tracker reference: [pm-h75tjh](../.agents/pm/issues/pm-h75tjh.toon).
+
+The release reliability gate declares `2026.8.7` as the minimum producer
+version for canonical `pm.error_code` and `pm.exit_code` tags. An unresolved
+event with a known older release is reported as `legacy_pre_contract`; it does
+not block a current release merely because it cannot satisfy a future
+producer contract.
+
+Events from the minimum producer or newer remain blocking when they are
+unexpected faults or lack the required tags. Events with no parseable producer
+version are also blocking. JSON output includes the minimum version,
+`legacy_pre_contract_total`, bounded legacy ids, and a bounded blocking-reason
+row for each current issue. Expected handled usage, not-found, and conflict
+errors remain a separate non-blocking class.
+
+This epoch rule only changes gate classification. It does not resolve, delete,
+or hide Sentry issues, and it does not weaken fatal or error thresholds for
+current producers.

package/docs/agent-task-token-baseline.json

@@ -14,12 +14,12 @@
     },
     {
       "id": "returning-agent",
-      "max_estimated_tokens": 336
+      "max_estimated_tokens": 383
     },
     {
       "id": "failing-command",
       "max_estimated_tokens": 197
     }
   ],
-  "composite_max_estimated_tokens": 2390
+  "composite_max_estimated_tokens": 2437
 }

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.8"
+    "version": "2026.8.9"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.8",
+      "version": "2026.8.9",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

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

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.8.8",
+  "version": "2026.8.9",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",