@unbrained/pm-cli 2026.8.21 → 2026.8.23

package/dist/sdk/test/trust.js

@@ -0,0 +1,207 @@
+/**
+ * @module sdk/test/trust
+ *
+ * Provides provenance and clone-local trust decisions for stored linked-test
+ * commands. Tracker items remain portable while execution acknowledgements stay
+ * outside the merge-unioned project record.
+ */
+
+!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]="30a61f26-5db8-50ba-af37-1990a4742ce8")}catch(e){}}();
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureDir, writeFileAtomic, } from "../../core/fs/fs-utils.js";
+import { sha256Hex, stableStringify } from "../../core/shared/serialization.js";
+import { isTimestampLiteral } from "../../core/shared/time.js";
+import { getRuntimePath } from "../../core/store/paths.js";
+const execFileAsync = promisify(execFile);
+const LINKED_TEST_TRUST_LEDGER_VERSION = 1;
+const LINKED_TEST_TRUST_LEDGER_FILE = "linked-test-trust.json";
+function trustLedgerPath(pmRoot) {
+    return path.join(getRuntimePath(pmRoot), LINKED_TEST_TRUST_LEDGER_FILE);
+}
+function emptyTrustLedger() {
+    return { version: LINKED_TEST_TRUST_LEDGER_VERSION, acknowledged: {} };
+}
+async function readTrustLedger(pmRoot) {
+    try {
+        const parsed = JSON.parse(await readFile(trustLedgerPath(pmRoot), "utf8"));
+        if (parsed.version !== LINKED_TEST_TRUST_LEDGER_VERSION ||
+            typeof parsed.acknowledged !== "object" ||
+            parsed.acknowledged === null ||
+            Array.isArray(parsed.acknowledged)) {
+            return emptyTrustLedger();
+        }
+        return {
+            version: LINKED_TEST_TRUST_LEDGER_VERSION,
+            acknowledged: parsed.acknowledged,
+        };
+    }
+    catch {
+        // A missing, corrupt, or unreadable ledger grants no acknowledgements.
+        // The local/source-ref provenance checks remain independent of this file.
+        return emptyTrustLedger();
+    }
+}
+/** Resolve the current Git branch without invoking a shell. */
+export async function resolveLinkedTestSourceRef(cwd = process.cwd()) {
+    const hostedRef = process.env.GITHUB_HEAD_REF?.trim() || process.env.GITHUB_REF_NAME?.trim();
+    if (hostedRef && hostedRef !== "merge") {
+        return hostedRef;
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
+        const ref = stdout.trim();
+        /* c8 ignore start -- successful git symbolic-ref output is non-empty by contract */
+        if (ref.length === 0)
+            return undefined;
+        /* c8 ignore stop */
+        return ref;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve the source checkout shared by linked-test provenance and execution. */
+export function resolveLinkedTestSourceWorkspaceRoot(cwd = process.cwd()) {
+    return process.env.PM_SOURCE_WORKSPACE_ROOT?.trim() || cwd;
+}
+function hasValidLinkedTestProvenance(provenance) {
+    if (provenance === null || typeof provenance !== "object")
+        return false;
+    return (typeof provenance.author === "string" &&
+        provenance.author.trim().length > 0 &&
+        typeof provenance.created_at === "string" &&
+        isTimestampLiteral(provenance.created_at) &&
+        (provenance.source_kind === "local_mutation" ||
+            provenance.source_kind === "merge_union"));
+}
+/** Build the optional ref portion shared by clone-local trust decisions. */
+function linkedTestTrustRefs(sourceRef, currentSourceRef) {
+    return {
+        ...(sourceRef ? { source_ref: sourceRef } : {}),
+        ...(currentSourceRef ? { current_source_ref: currentSourceRef } : {}),
+    };
+}
+/** Attach immutable author/time/ref provenance to newly stored commands. */
+export function attachLinkedTestProvenance(tests, author, createdAt, sourceRef) {
+    return tests?.map((test) => test.command && !test.provenance
+        ? {
+            ...test,
+            provenance: {
+                author,
+                created_at: createdAt,
+                source_kind: "local_mutation",
+                ...(sourceRef ? { source_ref: sourceRef } : {}),
+            },
+        }
+        : test);
+}
+/** Attach provenance while avoiding Git inspection for an empty mutation. */
+export async function attachLinkedTestMutationProvenance(tests, author, createdAt) {
+    if (!tests || tests.length === 0)
+        return tests;
+    const sourceWorkspaceRoot = resolveLinkedTestSourceWorkspaceRoot();
+    return attachLinkedTestProvenance(tests, author, createdAt, await resolveLinkedTestSourceRef(sourceWorkspaceRoot));
+}
+/** Produce the clone-local trust identity for one linked-test entry. */
+export function linkedTestTrustFingerprint(test) {
+    return sha256Hex(stableStringify({
+        command: test.command ?? null,
+        path: test.path ?? null,
+        scope: test.scope,
+        pm_context_mode: test.pm_context_mode ?? null,
+        workspace_context_mode: test.workspace_context_mode ?? null,
+        env_set: test.env_set ?? null,
+        env_clear: test.env_clear ?? null,
+        shared_host_safe: test.shared_host_safe ?? null,
+        provenance: test.provenance ?? null,
+        provenance_invalid: test.provenance_invalid ?? null,
+    }));
+}
+/** Resolve whether one stored command is trusted by this clone. */
+export async function resolveLinkedTestTrust(pmRoot, test, currentSourceRef) {
+    const ledger = await readTrustLedger(pmRoot);
+    return resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger);
+}
+function resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger) {
+    const fingerprint = linkedTestTrustFingerprint(test);
+    const sourceRef = test.provenance?.source_ref;
+    if (test.provenance === undefined &&
+        test.provenance_invalid !== true) {
+        return { fingerprint, trusted: true, reason: "legacy" };
+    }
+    const acknowledged = Object.hasOwn(ledger.acknowledged, fingerprint);
+    if (test.provenance_invalid === true ||
+        !hasValidLinkedTestProvenance(test.provenance)) {
+        if (acknowledged) {
+            return {
+                fingerprint,
+                trusted: true,
+                reason: "acknowledged",
+                ...linkedTestTrustRefs(undefined, currentSourceRef),
+            };
+        }
+        return {
+            fingerprint,
+            trusted: false,
+            reason: "invalid_provenance",
+            ...linkedTestTrustRefs(undefined, currentSourceRef),
+        };
+    }
+    if (test.provenance.source_kind === "local_mutation" &&
+        sourceRef === undefined) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "local_mutation",
+            ...linkedTestTrustRefs(undefined, currentSourceRef),
+        };
+    }
+    if (test.provenance.source_kind === "local_mutation" &&
+        sourceRef !== undefined &&
+        sourceRef === currentSourceRef) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "local_source_ref",
+            source_ref: sourceRef,
+            current_source_ref: currentSourceRef,
+        };
+    }
+    if (acknowledged) {
+        return {
+            fingerprint,
+            trusted: true,
+            reason: "acknowledged",
+            ...linkedTestTrustRefs(sourceRef, currentSourceRef),
+        };
+    }
+    return {
+        fingerprint,
+        trusted: false,
+        reason: "foreign_source_ref",
+        ...linkedTestTrustRefs(sourceRef, currentSourceRef),
+    };
+}
+/** Resolve a collection with one ledger read for validation and batch runs. */
+export async function resolveLinkedTestTrustBatch(pmRoot, tests, currentSourceRef) {
+    const ledger = await readTrustLedger(pmRoot);
+    return tests.map((test) => resolveLinkedTestTrustFromLedger(test, currentSourceRef, ledger));
+}
+/** Persist explicit clone-local acknowledgement for selected linked tests. */
+export async function acknowledgeLinkedTests(pmRoot, tests, acknowledgedAt) {
+    const ledger = await readTrustLedger(pmRoot);
+    const fingerprints = tests
+        .filter((test) => typeof test.command === "string" && test.command.length > 0)
+        .map(linkedTestTrustFingerprint);
+    for (const fingerprint of fingerprints) {
+        ledger.acknowledged[fingerprint] = { acknowledged_at: acknowledgedAt };
+    }
+    await ensureDir(path.dirname(trustLedgerPath(pmRoot)));
+    await writeFileAtomic(trustLedgerPath(pmRoot), `${JSON.stringify(ledger, null, 2)}\n`);
+    return { acknowledged: fingerprints.length, fingerprints };
+}
+//# sourceMappingURL=trust.js.map
+//# debugId=30a61f26-5db8-50ba-af37-1990a4742ce8

package/dist/types.d.ts

@@ -166,6 +166,17 @@ export interface LinkedFile {
     /** Value that configures or reports note for this contract. */
     note?: string;
 }
+/** Valid immutable provenance captured when a linked command enters tracker data. */
+export interface LinkedTestProvenance {
+    /** Author identity recorded by the originating mutation. */
+    author: string;
+    /** ISO 8601 time at which the command entered tracker data. */
+    created_at: string;
+    /** Mutation path that introduced the command. */
+    source_kind: "local_mutation" | "merge_union";
+    /** Best-effort Git branch or hosted head ref of the originating mutation. */
+    source_ref?: string;
+}
 /** Documents the linked test payload exchanged by command, SDK, and package integrations. */
 export interface LinkedTest {
     /** Value that configures or reports command for this contract. */
@@ -178,6 +189,12 @@ export interface LinkedTest {
     timeout_seconds?: number;
     /** Strategy used to control pm context behavior. */
     pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Strategy used for source-workspace visibility and command working directory. */
+    workspace_context_mode?: "source" | "isolated" | "snapshot";
+    /** Immutable provenance captured when the linked command enters tracker data. */
+    provenance?: LinkedTestProvenance;
+    /** Explicit fail-closed marker retained when stored provenance is malformed. */
+    provenance_invalid?: true;
     /** Value that configures or reports env set for this contract. */
     env_set?: Record<string, string>;
     /** Value that configures or reports env clear for this contract. */
@@ -558,6 +575,19 @@ 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";
+    /** Effective source-workspace mode used by the linked command. */
+    workspace_context_mode?: "source" | "isolated" | "snapshot";
+    /** Trust classification applied before execution. */
+    trust_reason?: "legacy" | "local_mutation" | "local_source_ref" | "acknowledged" | "invalid_provenance" | "foreign_source_ref";
+}
 /** 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 +620,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 {
@@ -1110,6 +1142,8 @@ export interface PmSettings {
     /** Value that configures or reports testing for this contract. */
     testing: {
         record_results_to_items: boolean;
+        /** Permit explicit one-shot execution of commands not yet trusted by this clone. */
+        allow_untrusted_linked_tests: boolean;
     };
     /** Value that configures or reports telemetry for this contract. */
     telemetry: {

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]="64223a83-1287-57ac-915d-dbd5e375a6eb")}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=64223a83-1287-57ac-915d-dbd5e375a6eb

package/docs/AGENT_PROVENANCE_ADR.md

@@ -10,7 +10,10 @@ Implementation lineage:
 resolution and patch-free historical reads implemented by
 [pm-ffz0a9](../.agents/pm/issues/pm-ffz0a9.toon),
 [pm-v8gfi7](../.agents/pm/issues/pm-v8gfi7.toon), and
-[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon).
+[pm-3yxwv5](../.agents/pm/issues/pm-3yxwv5.toon). Cross-harness adapters and
+operator-managed probe/vocabulary controls are tracked by
+[pm-c0lrdm](../.agents/pm/features/pm-c0lrdm.toon) and
+[pm-yds9dt](../.agents/pm/chores/pm-yds9dt.toon).
 
 Status: accepted amendment to
 [pm-qwuber](../.agents/pm/decisions/pm-qwuber.toon). The original stable-author
@@ -51,10 +54,13 @@ Provenance values are descriptive context, never authentication or
 authorization principals. Values are trimmed, length-bounded, and obtained only
 from literal descriptor keys, trusted caller data, or a named bounded resolver.
 Detection does not spawn processes, traverse process trees, evaluate user
-regexes, or access the network. The built-in Claude resolver may read only the
-tail of the current session's harness-owned JSONL file to recover its recorded
-model/version. It caps file bytes, lines, and line length, extracts only those
-two allow-listed values, and fails closed. `agent_identity.probes_enabled` or
+regexes, or access the network. The built-in Claude and Codex resolvers read
+only bounded windows of the current session's harness-owned JSONL file. Claude
+uses the recent tail to recover its recorded model/version. Codex uses the
+recent tail plus a bounded initial-head fallback for oversized sessions to
+recover allow-listed `turn_context.model` and `turn_context.effort` values.
+Both cap traversal, file bytes, lines, and line length, ignore all other fields,
+never follow symlinks, and fail closed. `agent_identity.probes_enabled` or
 `PM_AGENT_PROBES=off` disables every local resolver without disabling ordinary
 environment, argv, client, or host detection.
 
@@ -113,6 +119,11 @@ fabricate precision that was never captured.
 The aggregate and core SDK entrypoints export:
 
 - `AGENT_PROVENANCE_DIMENSIONS`;
+- `BUILTIN_AGENT_PROVENANCE_ADAPTERS`,
+  `listAgentProvenanceAdapters()`, and
+  `registerAgentProvenanceAdapters()`;
+- `normalizeAgentProvenanceAdapterValue()` for stable model-family and effort
+  vocabulary projections that retain the bounded raw observation;
 - `detectAgentIdentity()` and `detectHarnessIdentity()`;
 - `analyzeAgentProvenanceDescriptorCoverage()` for the descriptor capability
   matrix and negative controls;
@@ -138,6 +149,31 @@ Legacy author interpretation is workspace-owned data under
 version and whether a harness was `recorded`, resolved by `vocabulary`, or
 remains `unresolved`; immutable authors and hashes are never rewritten.
 
+`pm config get agent-identity-vocabulary`, `config list`, and `config export`
+publish only its `version` and `alias_count`. Typed mutations use the existing
+config transport:
+
+```bash
+pm config set agent-identity-probes-enabled false
+pm config set agent-identity-vocabulary --policy preview-add \
+  --value "Legacy Codex=codex" --criterion "Legacy Codex" --criterion "Alice"
+pm config set agent-identity-vocabulary --policy add \
+  --value "Legacy Codex=codex"
+pm config set agent-identity-vocabulary --policy remove --value "Legacy Codex"
+```
+
+`preview-*` policies perform no write and report the exact residual unique
+author count without returning author spellings. Real add/remove/clear changes
+bump the vocabulary revision once; identical adds and absent removes are
+idempotent. Aliases for already canonical `harness:<name>` authors fail closed.
+
+Every built-in interactive harness has a contract-versioned adapter with an
+implementation version, priority, covered dimensions, source classes,
+normalization revisions, confidence, waivers, and immutable probe bounds.
+Packages may register a new namespace or explicitly replace a built-in only at
+a higher priority. Equal-priority ambiguity and descriptor mismatch fail
+closed, and the disposer restores the prior adapter.
+
 The SDK/CLI matrix classifies every input as shared, positional, transport,
 presentation, local adapter, scope selector, compatibility alias, or SDK-native.
 An unknown CLI flag fails closed as `unclassified`. Committed test baselines cap

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/CONFIGURATION.md

@@ -29,6 +29,7 @@ pm config project export --json
 pm config project get item-format --json
 pm config project set item-format --format toon
 pm config project set test-result-tracking --policy enabled
+pm config project set untrusted-linked-test-execution --policy disabled
 ```
 
 `config set <key> <value>` also accepts the value as a positional argument; pm routes
@@ -85,6 +86,7 @@ When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and
 | `history.compact_policy.max_entries`       | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`)                                  |
 | `history.compact_policy.trigger`           | policy intent when enabled: `health_warn` (advisory only) or `auto` (scheduled sweeps expected)                                                                                                       |
 | `testing.record_results_to_items`          | persist bounded linked-test summaries                                                                                                                                                                 |
+| `testing.allow_untrusted_linked_tests`     | permit the explicit `pm test --allow-untrusted-linked-tests` one-run override (default `false`; does not trust or execute commands by itself)                                                         |
 | `validation.sprint_release_format`         | `warn` or `strict_error`                                                                                                                                                                              |
 | `validation.parent_reference`              | `warn` or `strict_error` (`strict_error` is the built-in default; `pm create --allow-missing-parent` is the explicit escape hatch)                                                                    |
 | `item_types.definitions[]`                 | custom item types and type options                                                                                                                                                                    |
@@ -115,6 +117,7 @@ pm config project set schema_unknown_field_policy reject   # (schema.unknown_fie
 pm config project set governance-duplicate-detection-mode strict         # (governance.duplicate_detection_mode) off | advisory | strict
 pm config project set governance-duplicate-detection-threshold 0.8       # (governance.duplicate_detection_threshold) ratio 0..1
 pm config project set governance-duplicate-detection-limit 3             # (governance.duplicate_detection_limit) integer 0..20
+pm config project set untrusted-linked-test-execution disabled            # (testing.allow_untrusted_linked_tests) enabled | disabled
 ```
 
 Duplicate governance uses the shared SDK scorer and bounded metadata query
@@ -227,6 +230,7 @@ pm config project set sprint-release-format-policy --policy warn
 pm config project set parent-reference-policy --policy strict_error
 pm config project set history-missing-stream-policy --policy auto_create
 pm config project set test-result-tracking --policy enabled
+pm config project set untrusted-linked-test-execution --policy disabled
 ```
 
 Use standalone checks when validating a repository:

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,