@unbrained/pm-cli 2026.8.21 → 2026.8.22

package/dist/sdk/test/batch.js

@@ -4,7 +4,7 @@
  * Implements the pm test all command surface and its agent-facing runtime behavior.
  */
 
-!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]="aeb0a1a7-bc73-5c56-bbed-9472c651b5f6")}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]="bb2758a5-a5c1-5f6e-be42-0e173fe16fe3")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -15,7 +15,7 @@ import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { nowIso } from "../../core/shared/time.js";
 import { listAllItemMetadataLight } from "../../core/store/item-store.js";
-import { resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { resolveGlobalPmRoot, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { appendTrackedTestRunSummary } from "../../core/test/item-test-run-tracking.js";
 import { resolveAuthor } from "../../core/shared/author.js";
@@ -245,7 +245,7 @@ const runTestAllItem = async (entry, context) => {
     });
     const summary = countStatuses(runResults);
     const failureCategories = countFailureCategories(runResults);
-    const trackingWarnings = await appendTestAllItemTracking(entry, summary, context);
+    const trackingWarnings = await appendTestAllItemTracking(entry, summary, runResults, context);
     return {
         passed: summary.passed,
         failed: summary.failed,
@@ -273,7 +273,7 @@ const trackedRunFailed = (summary, options) => [
 ].includes(true);
 /** Projects true flags while keeping false values absent from persisted rows. */
 const optionalTrue = (value) => value ? true : undefined;
-const appendTestAllItemTracking = async (entry, summary, context) => {
+const appendTestAllItemTracking = async (entry, summary, runResults, context) => {
     if (!context.trackingEnabled) {
         return [];
     }
@@ -300,6 +300,14 @@ const appendTestAllItemTracking = async (entry, summary, context) => {
                 items: 1,
                 linked_tests: entry.tests.length,
                 fail_on_skipped_triggered: optionalTrue(context.options.failOnSkipped === true && summary.skipped > 0),
+                executions: runResults
+                    .filter((result) => result.command?.trim())
+                    .slice(0, 32)
+                    .map((result) => ({
+                    command: result.command.trim(),
+                    requested_pm_context_mode: result.execution_context?.requested_pm_context_mode,
+                    pm_context_mode: result.execution_context?.pm_context_mode,
+                })),
             },
         });
     }
@@ -487,4 +495,4 @@ export const _testOnlyTestAll = {
     formatTrackingError,
 };
 //# sourceMappingURL=batch.js.map
-//# debugId=aeb0a1a7-bc73-5c56-bbed-9472c651b5f6
+//# debugId=bb2758a5-a5c1-5f6e-be42-0e173fe16fe3

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test command surface and its agent-facing runtime behavior.
  */
 
-!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]="2354c553-3a81-59d8-9c0a-3d19cd3cedd2")}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]="5fe0ee3e-9590-56fc-b238-e56ff1970e52")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
@@ -1791,6 +1791,14 @@ function buildTrackedTestRunSummary(params) {
         skipped: summary.skipped,
         fail_on_skipped_triggered: params.failOnSkippedTriggered ? true : undefined,
         measurements: measurements.length > 0 ? measurements : undefined,
+        executions: params.runResults
+            .filter((result) => result.command?.trim())
+            .slice(0, 32)
+            .map((result) => ({
+            command: result.command.trim(),
+            requested_pm_context_mode: result.execution_context?.requested_pm_context_mode,
+            pm_context_mode: result.execution_context?.pm_context_mode,
+        })),
     };
 }
 async function recordTestRunSummary(params) {
@@ -1964,4 +1972,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=2354c553-3a81-59d8-9c0a-3d19cd3cedd2
+//# debugId=5fe0ee3e-9590-56fc-b238-e56ff1970e52

package/dist/types.d.ts

@@ -558,6 +558,15 @@ export interface TestRunMeasurement {
     /** ISO 8601 timestamp binding the measurement to its producing run. */
     recorded_at: string;
 }
+/** Bounded command and tracker-context provenance for one linked-test execution. */
+export interface ItemTestRunExecution {
+    /** Exact linked command selected for execution. */
+    command: string;
+    /** Context mode requested before linked-test overrides or auto-remediation. */
+    requested_pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Effective context mode used by the linked command. */
+    pm_context_mode?: "schema" | "tracker" | "auto";
+}
 /** Documents the item test run summary payload exchanged by command, SDK, and package integrations. */
 export interface ItemTestRunSummary {
     /** Executes the id operation through the package runtime. */
@@ -590,6 +599,8 @@ export interface ItemTestRunSummary {
     fail_on_skipped_triggered?: boolean;
     /** Bounded, deterministic quantitative evidence produced by this run. */
     measurements?: TestRunMeasurement[];
+    /** Commands and effective tracker contexts bound to this recorded run. */
+    executions?: ItemTestRunExecution[];
 }
 /** Documents the item metadata payload exchanged by command, SDK, and package integrations. */
 export interface ItemMetadata {

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="f6ab5bae-53b3-5feb-b89f-46e64afe7058")}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]="13c65470-8f5f-59ca-acb5-50c926c68870")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=f6ab5bae-53b3-5feb-b89f-46e64afe7058
+//# debugId=13c65470-8f5f-59ca-acb5-50c926c68870

package/docs/AGENT_UX_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Agent UX Contracts
 
-Tracker references: [pm-v1yo](../.agents/pm/issues/pm-v1yo.toon), [pm-i6pi](../.agents/pm/issues/pm-i6pi.toon), [pm-um4g](../.agents/pm/issues/pm-um4g.toon), [pm-tmhs](../.agents/pm/issues/pm-tmhs.toon), [pm-6m1i](../.agents/pm/issues/pm-6m1i.toon), [pm-cj9v](../.agents/pm/issues/pm-cj9v.toon), [pm-yp56](../.agents/pm/issues/pm-yp56.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), and [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon).
+Tracker references: [pm-v1yo](../.agents/pm/issues/pm-v1yo.toon), [pm-i6pi](../.agents/pm/issues/pm-i6pi.toon), [pm-um4g](../.agents/pm/issues/pm-um4g.toon), [pm-tmhs](../.agents/pm/issues/pm-tmhs.toon), [pm-6m1i](../.agents/pm/issues/pm-6m1i.toon), [pm-cj9v](../.agents/pm/issues/pm-cj9v.toon), [pm-yp56](../.agents/pm/issues/pm-yp56.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon), [pm-rggtvd](../.agents/pm/issues/pm-rggtvd.toon), and [pm-vk7zek](../.agents/pm/issues/pm-vk7zek.toon).
 
 These contracts keep common agent loops deterministic, token-efficient, and recoverable. Runtime contracts and `--help --json` remain the exact source for available flags.
 
@@ -13,9 +13,25 @@ The public SDK exports `collectNewOrderingCycleWarnings(beforeItems, afterItems,
 Dependency removal is lossless. `--dep-remove` rejects the same malformed
 shorthand as `--dep`, and a selector that matches nothing returns the typed
 `dependency_remove_no_match` refusal instead of a successful no-op. Exact
-duplicate rows can be normalized without delete-then-add risk by re-adding the
-same `id`, `kind`, and `source_kind`; the mutation keeps one canonical row and
-never removes the logical edge.
+rows can be retired by selecting `id`, `kind` (or its input-only `type` alias),
+`source_kind`, `author`, and `created_at`; omitted coordinates intentionally broaden the match. Exact
+duplicate rows can still be normalized without delete-then-add risk by
+re-adding the same identity; the mutation keeps one canonical row and never
+removes the logical edge. Identity comparison includes normalized `id`, `kind`,
+`source_kind`, `author`, and creation instant, preserving provenance-distinct
+siblings.
+
+Hierarchy mutations are stricter than ordering advisories. `pm create` and
+`pm update` refuse a new cycle, registry cardinality breach, or contradictory
+scalar/dependency parent before writing. The structured refusal names the
+changed holder plus the cycle members or competing parents. Existing legacy
+debt remains mutable only toward a cleaner state, so repair does not require a
+global bypass. Read paths canonicalize every registry-declared hierarchy kind;
+an item cannot disappear from `pm list --parent` or `pm get --tree` merely
+because an integration used a dependency row instead of the scalar field.
+`pm update-many` applies the same hierarchy guard independently to each matched
+item: one refused row is reported as failed while other rows may still commit,
+so a bulk hierarchy mutation is not atomic across the complete match set.
 
 `pm graph audit` uses two explicit units:
 

package/docs/COMMANDS.md

@@ -6,6 +6,8 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
 
 Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
 
+Create-safe init prefix normalization is tracked by [pm-gh1073](../.agents/pm/issues/pm-gh1073.toon).
+
 ```bash
 pm <command> --help
 pm <command> --help --json
@@ -49,21 +51,21 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 
 ## Command Families
 
-| Family       | Commands                                                                                                                       | Purpose                                                                                                                                                                                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                        | create and inspect tracker setup                                                                                                                                                                                                                       |
+| Family       | Commands                                                                                                                                      | Purpose                                                                                                                                                                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                                       | create and inspect tracker setup                                                                                                                                                                                                                       |
 | Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `item reopen`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state, including terminal-work recurrence without duplicate creation                                                                                                                                                                       |
-| Bulk         | `item mutate`, `item complete`, `update-many`, `close-many`                                                                    | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
-| Scheduling   | `meet`, `event`, `remind`                                                                                                      | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
-| Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`      | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
-| Links        | `files`, `docs`, `test`, `deps`                                                                                                | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
-| Verification | `test`, `test-all`, `test-runs`†, `validate`, `gc`                                                                             | run linked tests and repository checks                                                                                                                                                                                                                 |
-| History      | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats`                               | inspect, compact, redact, re-anchor, and recover item state                                                                                                                                                                                            |
-| Schema       | `schema add/remove-*` / `rename-type` / `rename-field` / `remap-status` / `apply-preset`                                       | manage config-driven types, statuses, and fields; losslessly migrate existing items when definitions evolve; adopt presets or infer types                                                                                                              |
-| Profiles     | `profile list` / `show` / `apply` / `lint`                                                                                     | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
-| Calendar     | `calendar`, `cal`                                                                                                              | project deadlines, reminders, and events                                                                                                                                                                                                               |
-| Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                     | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
-| Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                             | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
+| Bulk         | `item mutate`, `item complete`, `update-many`, `close-many`                                                                                   | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
+| Scheduling   | `meet`, `event`, `remind`                                                                                                                     | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
+| Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`                     | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
+| Links        | `files`, `docs`, `test`, `deps`                                                                                                               | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
+| Verification | `test`, `test-all`, `test-runs`†, `validate`, `gc`                                                                                            | run linked tests and repository checks                                                                                                                                                                                                                 |
+| History      | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats`                                              | inspect, compact, redact, re-anchor, and recover item state                                                                                                                                                                                            |
+| Schema       | `schema add/remove-*` / `rename-type` / `rename-field` / `remap-status` / `apply-preset`                                                      | manage config-driven types, statuses, and fields; losslessly migrate existing items when definitions evolve; adopt presets or infer types                                                                                                              |
+| Profiles     | `profile list` / `show` / `apply` / `lint`                                                                                                    | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
+| Calendar     | `calendar`, `cal`                                                                                                                             | project deadlines, reminders, and events                                                                                                                                                                                                               |
+| Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                                    | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
+| Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                                            | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
 
 `†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm install linked-test-adapters --project`).
 
@@ -89,6 +91,15 @@ ID prefix without relying on the legacy positional form. `pm init ops` remains
 compatible, and supplying both forms is accepted only when they normalize to the
 same prefix; conflicting values fail with `init_id_prefix_conflict` instead of
 silently choosing one.
+Prefixes normalize through the same primitive used by item creation: letters
+become lowercase, each run of whitespace or punctuation becomes one `-`, edge
+separators are removed, and exactly one trailing `-` is stored. For example,
+`"Release Candidate"` persists as `release-candidate-`; an input with no ASCII
+letters or digits falls back to `pm-`. Path-like values remain invalid tracker
+prefixes when passed through `--id-prefix`; a path-like positional value remains
+the advanced tracker-root target described below. To repair an older unsafe
+value, rerun init with a safe prefix and explicit replacement intent, for example
+`pm init --id-prefix "release candidate" --force --defaults`.
 Use `pm init --workspace <dir>` when `<dir>` is a project root; it creates `<dir>/.agents/pm`. A path-like positional remains the advanced tracker-root form and writes tracker files directly at that path. Both explicit target forms return `target.mode`, `target.tracker_root`, and tracker-scoped executable `next_steps` so agents can run the suggestions from any working directory.
 Implicit init discovery also reports whether the selected tracker is local or was found in an ancestor. If `pm init <name>` would change an ancestor tracker, the refusal names both directories and gives the safe current-directory retry: `pm init <name> --pm-path "$PWD/.agents/pm" --defaults`.
 `pm init --agent-guidance ask` is the default behavior: prompt in TTY only when AGENTS/CLAUDE guidance is missing and no decline is recorded.
@@ -163,6 +174,10 @@ 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.
+As a read-only structured surface, `duplicates` accepts the universal output
+controls, including `--output-format json`, `--lean`, projection/amount
+controls, and token accounting, while its default TOON output remains bounded.
+Tracked by [pm-gh1076](../.agents/pm/issues/pm-gh1076.toon).
 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.
 
 When the strongest duplicate match is terminal because the same work recurred,

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -1,6 +1,6 @@
 # Dependency-kind contract
 
-Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), and [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon).
+Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon), [pm-rggtvd](../.agents/pm/issues/pm-rggtvd.toon), and [pm-vk7zek](../.agents/pm/issues/pm-vk7zek.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.
 
@@ -15,9 +15,17 @@ Dependency rows have one canonical stored spelling per relationship meaning. Com
 
 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.
 
+Extension kinds may opt into both ordering and hierarchy semantics. Unless they
+declare an explicit `traversal`, ordering is the primary traversal and context
+role family; hierarchy direction and cardinality remain enforceable integrity
+constraints. This ordering-first precedence is shared by registry snapshots and
+direct-edge context explanations.
+
 Dependency additions and removals share the same lossless input grammar. A
-bare value is an item id; structured input uses `id=<id>` plus an optional
-canonical `kind`/`type` and `source_kind`. Punctuation-shaped shorthand such as
+bare value is an item id; structured removal input uses `id=<id>` plus optional
+canonical `kind` (with `type` accepted only as an input alias), `source_kind`, `author`, and ISO `created_at`
+selectors. Supplying all stored coordinates retires exactly one dependency row
+without deleting siblings that share an id and kind. Punctuation-shaped shorthand such as
 `OTHER,related` is rejected with `dependency_flag_value_invalid` on both
 `--dep` and `--dep-remove`, before prefix normalization can turn it into a
 dangling id. A removal selector that matches no stored row fails with
@@ -25,6 +33,26 @@ dangling id. A removal selector that matches no stored row fails with
 available identities. Re-adding a stored dependency identity is idempotent; if
 legacy storage contains that exact identity more than once, the same mutation
 collapses the touched copies to one without creating an edge-absence window.
+The stored identity includes normalized `id`, `kind`, `source_kind`, `author`,
+and creation instant, so provenance-distinct sibling rows remain independent.
+
+## Hierarchy integrity
+
+The registry's `hierarchy`, `hierarchyDirection`, `outgoing`, and `incoming`
+fields are executable contracts. Scalar `parent` metadata and every registered
+hierarchy dependency spelling normalize into the same parent-to-child relation.
+That normalized relation powers `pm list --parent`, list/get tree projections,
+child rollups, graph traversal, graph analysis, graph audit, validate, and
+health. Extensions therefore gain hierarchy behavior by registering semantics;
+consumers do not hard-code kind names.
+
+Create and update transactions reject a newly introduced hierarchy cycle,
+registry cardinality violation, or scalar/dependency direction contradiction
+before persistence. Existing debt remains readable and repairable. Active debt
+is gate-failing in graph governance and health; defects confined to terminal
+items are labeled legacy and are never mutated automatically. `pm validate`
+reports cycle, cardinality, and parent-divergence counts and exact bounded rows,
+while `pm graph analyze` exposes a compact `hierarchy` summary.
 
 `recurs_from` has no alias: a later occurrence points to an earlier occurrence.
 It is persistent after both items become terminal and carries temporal identity,

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -0,0 +1,98 @@
+# Diagnostic Output Contracts
+
+Tracker references: [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+
+## Agent Quick Context
+
+Failures are context-management surfaces. Every diagnostic family now declares
+a format-aware token ceiling and one degradation ladder in the public SDK:
+
+| Class                | Text | JSON | Corrective action that survives degradation |
+| -------------------- | ---: | ---: | ------------------------------------------- |
+| `error`              |  768 | 2000 | required action, retry/domain, or next step |
+| `warning`            |  768 | 2000 | required action, retry/domain, or next step |
+| `validation_summary` | 1500 | 3000 | required action, retry/domain, or next step |
+| `recovery_bundle`    |  768 | 2000 | required action, retry/domain, or next step |
+
+The smallest explicit ceiling is 192 estimated tokens. At that floor, the
+projector may reduce the diagnostic to its code, required action, compact
+recovery, and exit status. It never removes the first corrective action.
+
+## SDK Contract
+
+Use the public contract surface rather than maintaining a package-local error
+budget:
+
+```ts
+import {
+  PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS,
+  projectPmDiagnosticOutput,
+  projectPmDiagnosticText,
+  resolvePmDiagnosticOutputBudget,
+} from "@unbrained/pm-cli/sdk/contracts";
+
+const contract = resolvePmDiagnosticOutputBudget("error");
+const projected = projectPmDiagnosticOutput(
+  {
+    code: "invalid_argument_value",
+    required: "Use --status open and retry.",
+    recovery: { suggested_retry: "pm list --status open" },
+    detail: "The supplied status is not declared.",
+    exit_code: 2,
+  },
+  { maxEstimatedTokens: contract.minimum_max_estimated_tokens },
+);
+
+const text = projectPmDiagnosticText(
+  "A long rendered diagnostic",
+  "Use --status open and retry.",
+).output;
+```
+
+The JSON projector orders `code`, `required`, recovery, and next steps before
+explanation. Untruncated diagnostics add no per-call receipt overhead; their
+binding declaration is discoverable from `pm contracts --full --json` under
+`diagnostic_output_contracts`. When degradation occurs, the returned
+`diagnostic_output` receipt records the effective budget, original and emitted
+estimates, applied stages, and omitted top-level fields. Minimal fallbacks bound
+the named omission list and disclose any additional count through
+`omitted_fields_overflow_count`.
+
+The deterministic ladder is:
+
+1. full diagnostic;
+2. omit explanation;
+3. limit diagnostic collections;
+4. compact recovery to actionable keys;
+5. retain the action-only envelope.
+
+Human diagnostics lead with `What is required` and next steps before explaining
+what happened. If their declared ceiling binds, the compact text still begins
+with the required action and points to structured JSON for the bounded recovery
+envelope.
+
+## Executable Assurance
+
+`pnpm quality:recovery-closure` builds the current CLI and replays 22 refusal
+contracts in isolated trackers. Ten representative, high-frequency failure
+paths are also ratcheted by
+`scripts/release/diagnostic-output-baseline.json`. The gate requires every row
+to remain within the SDK-declared JSON ceiling and retain a mechanically
+actionable correction. It reports the aggregate original and emitted token
+estimates without claiming a reduction when no degradation was required.
+
+The baseline is a coverage ratchet, not permission to weaken a ceiling. Its
+negative control requires a missing baseline probe to fail. The existing
+refusal-closure negative controls independently prove that incomplete domains,
+broken retries, and malformed recovery envelopes remain blocking findings.
+
+Run the focused proof with:
+
+```bash
+pnpm build
+node scripts/release/refusal-closure-gate.mjs
+node scripts/run-tests.mjs test -- \
+  tests/unit/sdk/agent-output-contracts.spec.ts \
+  tests/unit/cli/error-guidance.spec.ts \
+  tests/unit/scripts/refusal-closure-gate.spec.ts
+```

package/docs/EXTENSIONS.md

@@ -45,6 +45,7 @@ pm install kanban --project
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.
 Registry dependency names and versions are parsed as npm package specs before the install subprocess starts. Leading-option names and shell control syntax are rejected. npm reads those validated dependencies from an isolated runtime-only manifest; no caller-controlled spec is forwarded through the Windows command shell, and the fixed invocation still ends option parsing with `--`. Runtime verification then activates a temporary snapshot of the complete installed extension directory, so an upgrade cannot silently reuse stale transitive ESM dependencies from the current process. Successful install details expose `module_graph_verification: "fresh_snapshot"` for this check.
+pm-owned npm subprocesses clear any inherited, case-insensitive `npm_config_allow_scripts` value while retaining registry, auth, proxy, and executable-path environment; `--ignore-scripts` remains authoritative. Tracked by [pm-gh1072](../.agents/pm/issues/pm-gh1072.toon).
 An explicit `--pm-path` scopes project installs to that tracker root, including extension files, managed state, settings, type-folder scaffolding, and verification output. This is the safe form for temporary package testing from inside another repository checkout.
 
 ```bash
@@ -308,7 +309,7 @@ Common APIs:
 - `api.registerMigration(definition)` adds schema migrations.
 - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
 - `api.registerAssuranceMeasurementProvider(provider)` contributes typed measurements to assurance. It requires `services`; network providers also require manifest `permissions.network: true`. Gates allow providers and cost/network limits per trigger. See [Project Assurance Primitives](ASSURANCE.md#extension-measurement-providers) for examples.
-- `api.registerService("output_format", handler)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result.
+- `api.registerService("output_format", handler, ownership?)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. An override that is unconditionally inert can declare `{ passThrough: true }`; the host then ignores and diagnoses any handled result, and package doctor treats the registration as statically safe. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result. Tracked by [pm-gh1074](../.agents/pm/issues/pm-gh1074.toon).
 - `api.registerRenderer("toon" | "json", renderer, ownership?)` adds format-specific renderers. Scope ownership with `commands` and/or a `resultDiscriminator`; the host checks both before invoking the renderer and falls back to native rendering for unrelated output. The legacy unscoped callback remains supported, but doctor warns because package ownership cannot be proven statically.
 - `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
 - `api.hooks.beforeCommand(handler)`, `api.hooks.beforeMutation(handler)`, `api.hooks.afterCommand(handler)`, `api.hooks.onWrite(handler)`, `api.hooks.onRead(handler)`, and `api.hooks.onIndex(handler)` add lifecycle hooks.

package/docs/README.md

@@ -51,6 +51,7 @@ pm guide release --json
 - [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.
+- [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
 - [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.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
 
 ## Agent Quick Context
 
@@ -140,7 +140,7 @@ pm stats --output-row-contract
 pm contracts --full --json
 ```
 
-Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
+Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed option provenance, deterministic estimated token count, string/row compaction signals, and budget outcome. When canonical controls are present, `canonical_options_used` records spellings such as `--output-include`; the optional field is omitted when no canonical control was supplied so minimum-budget session receipts remain compact. `legacy_aliases_used` and `migration_hints` record only compatibility flags the caller actually supplied. A command-local flag synthesized internally to execute a canonical projection mode is therefore never misreported as deprecated syntax. When both spellings are supplied, both provenance arrays report that mixed invocation. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
 When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
 
@@ -179,6 +179,13 @@ key. Health retains at most 100 warning rows and reports `warning_count`,
 projection unless `--full` is explicit, keeping the failing check identities
 and warning codes inside the ordinary budget.
 
+Failure transports use the companion
+[Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md). Those contracts
+bind errors, warnings, validation summaries, and recovery bundles independently
+from successful command results. Corrective actions precede explanation and
+survive every degradation stage, while untruncated JSON avoids a per-call
+receipt tax.
+
 ## SDK and Package Usage
 
 Typed `PmClient` read methods accept `PmReadOutputOptions` directly:

package/docs/RELATIONSHIP_GRAPH.md

@@ -314,9 +314,12 @@ outcome milestones are roots, not work subjects, and are excluded from those
 populations. Rate or
 all-status floors are lifecycle-stable; an absolute active-population floor is
 invalid because completing reachable work legitimately moves it into the
-terminal population. `finding_subjects_by_code` includes every known finding
-code even when its population is zero, so assurance selectors never confuse a
-clean class with a missing contract field.
+terminal population. Detailed output's nested SDK profile census,
+`finding_subjects_by_code`, includes every known finding code even when its
+population is zero, so assurance selectors never confuse a clean class with a
+missing contract field. The top-level audit and persisted-baseline census is
+`affected_subjects_by_code`; both fields count affected subjects, but their
+locations and consumers differ and neither is an alias for the other.
 
 ```ts
 import {

package/docs/TESTING.md

@@ -366,6 +366,18 @@ The manifest records baseline bytes and estimated tokens for visible review
 deltas. Updating it cannot raise answer ceilings, which remain owned by
 `PM_COMMAND_OUTPUT_BUDGET_CONTRACTS`.
 
+Diagnostic ceilings share the executable refusal gate:
+
+```bash
+pnpm quality:recovery-closure
+```
+
+The gate replays 22 refusal contracts and ratchets ten representative failure
+paths against `PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS`. Every diagnostic must fit
+its declared JSON ceiling and preserve a mechanically actionable correction;
+the missing-probe negative control proves that the diagnostic corpus cannot
+silently shrink.
+
 The gate derives every supported harness, model, session, and provenance
 environment key from the SDK-owned harness descriptor registry. It deletes
 those host inputs before each fixture invocation, then supplies only the
@@ -480,6 +492,9 @@ pm test <item-id> --metric-below coverage=100 --metric-diff p95_latency
 
 Measurements are stored on the producing `test_runs` row, retained with the
 bounded run history, and exposed consistently by CLI, SDK, MCP, and contracts.
+Each recorded row also keeps a bounded `executions` list with the exact linked
+command plus its requested and effective `pm_context_mode`, so tracker-backed
+verification remains attributable after the transient process logs are gone.
 
 ## Linked-Test Assertions
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.21",
+  "version": "2026.8.22",
   "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.21",
+  "version": "2026.8.22",
   "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.21",
+  "version": "2026.8.22",
   "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.21",
+  "version": "2026.8.22",
   "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.21",
+  "version": "2026.8.22",
   "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.21",
+  "version": "2026.8.22",
   "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.21",
+  "version": "2026.8.22",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",