@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/sdk/schema.js

@@ -4,7 +4,8 @@
  * Owns typed schema customization primitives shared by SDK, CLI, and MCP consumers.
  */
 
-!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]="2ab8a5a9-dbea-526f-a541-b7ca2b106ac5")}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]="6112923d-5e06-5839-b452-a32818c6398d")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { resolveAuthor } from "../core/shared/author.js";
@@ -24,7 +25,7 @@ import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { nowIso } from "../core/shared/time.js";
 import { getActiveExtensionRegistrations, runActiveOnWriteHooks, } from "../core/extensions/index.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings, resolveGovernanceKnobs, } from "../core/store/settings.js";
 import { resolvePmToolCustomFieldCollision } from "./cli-contracts/tool-schema.js";
 /** Public contract for schema subcommands, shared by SDK and presentation-layer consumers. */
@@ -160,9 +161,7 @@ export async function runSchemaAddType(name, options, global) {
     };
 }
 async function ensureInitialized(pmRoot) {
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
 }
 /**
  * Reconcile the committed merge-driver fence with the type folders that exist
@@ -1365,4 +1364,4 @@ export const _testOnlySchemaCommand = {
     workflowSlotsReferencing,
 };
 //# sourceMappingURL=schema.js.map
-//# debugId=2ab8a5a9-dbea-526f-a541-b7ca2b106ac5
+//# debugId=6112923d-5e06-5839-b452-a32818c6398d

package/dist/sdk/similarity.d.ts

@@ -115,6 +115,19 @@ export interface SimilarityAdvisory {
     bypassed: boolean;
     /** Shared similarity query result. */
     result: SimilarItemsResult;
+    /** Executable next action selected from the strongest matching item's lifecycle state. */
+    recovery: SimilarityRecovery;
+}
+/** Executable duplicate-intake recovery selected from the strongest match. */
+export interface SimilarityRecovery {
+    /** Whether to continue existing active work or reopen terminal work as a recurrence. */
+    action: "reuse" | "reopen";
+    /** Strongest matching canonical item. */
+    item_id: string;
+    /** Shell-form recovery command. */
+    command: string;
+    /** Tokenized recovery command for direct execution. */
+    args: string[];
 }
 /** Render compact warning tokens shared by create and copy results. */
 export declare function similarityAdvisoryWarnings(advisory: SimilarityAdvisory | undefined): string[];

package/dist/sdk/similarity.js

@@ -5,11 +5,11 @@
  * governance and package-owned duplicate analysis.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a2fad90a-3575-5f3e-8cbe-ac380ac45591")}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]="33a43890-abcf-58fc-bf9d-bf2619d4cf35")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
-import { normalizeStatusInput } from "../core/item/status.js";
+import { isTerminalStatus, normalizeStatusInput } from "../core/item/status.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import { listAllItemMetadataLight } from "../core/store/item-store.js";
 import { resolvePmRoot } from "../core/store/paths.js";
@@ -32,8 +32,28 @@ export function similarityAdvisoryWarnings(advisory) {
             `likely_duplicates:${advisory.result.items
                 .map((item) => item.id)
                 .join(",")}`,
+            `likely_duplicate_recovery:${advisory.recovery.action}:${advisory.recovery.item_id}`,
         ];
 }
+async function resolveSimilarityRecovery(result, options) {
+    const strongest = result.items[0];
+    const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
+    const statusRegistry = resolveRuntimeStatusRegistry((await readSettings(pmRoot)).schema);
+    if (isTerminalStatus(strongest.status, statusRegistry)) {
+        return {
+            action: "reopen",
+            item_id: strongest.id,
+            command: `pm item reopen ${strongest.id} "<recurrence reason>"`,
+            args: ["item", "reopen", strongest.id, "<recurrence reason>"],
+        };
+    }
+    return {
+        action: "reuse",
+        item_id: strongest.id,
+        command: `pm get ${strongest.id} --full`,
+        args: ["get", strongest.id, "--full"],
+    };
+}
 function validateSimilarityOptions(options) {
     const limit = options.limit ?? DEFAULT_SIMILARITY_LIMIT;
     const threshold = options.threshold ?? DEFAULT_SIMILARITY_THRESHOLD;
@@ -287,20 +307,26 @@ export async function evaluateSimilarityGovernance(candidate, options) {
     const result = await findSimilarItems(candidate, options);
     if (result.count === 0)
         return undefined;
+    const recovery = await resolveSimilarityRecovery(result, options);
     const bypassed = options.mode === "strict" && options.allowDuplicate === true;
     if (options.mode === "strict" && !bypassed) {
         const candidates = result.items
             .map((item) => `${item.id} (${item.status}): ${item.title}`)
             .join("; ");
-        throw new PmCliError(`Likely duplicate item(s) found: ${candidates}. Reuse the canonical item or pass --allow-duplicate with explicit intent.`, EXIT_CODE.CONFLICT, {
+        const recoveryInstruction = recovery.action === "reopen"
+            ? "Reopen the canonical item"
+            : "Reuse the canonical item";
+        throw new PmCliError(`Likely duplicate item(s) found: ${candidates}. ${recoveryInstruction} or pass --allow-duplicate with explicit intent.`, EXIT_CODE.CONFLICT, {
             code: "likely_duplicate",
-            required: "Reuse an existing item, or explicitly acknowledge the duplicate with --allow-duplicate.",
+            required: `${recoveryInstruction}, or explicitly acknowledge the duplicate with --allow-duplicate.`,
             recovery: {
                 suggested_flags: ["--allow-duplicate"],
+                suggested_retry: recovery.command,
+                suggested_retry_args: recovery.args,
             },
         });
     }
-    return { mode: options.mode, bypassed, result };
+    return { mode: options.mode, bypassed, result, recovery };
 }
 //# sourceMappingURL=similarity.js.map
-//# debugId=a2fad90a-3575-5f3e-8cbe-ac380ac45591
+//# debugId=33a43890-abcf-58fc-bf9d-bf2619d4cf35

package/dist/sdk/stats.js

@@ -4,7 +4,8 @@
  * Implements the pm stats 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]="d28c7ac7-9801-5b0c-84c9-51deede398be")}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]="b56db1fc-d989-5d18-8b29-336a03f1e525")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -15,11 +16,9 @@ import { enforceHistoryStreamPolicyForItems } from "../core/history/history-stre
 import { computeHistoryStorageStats, } from "../core/history/history-storage-stats.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
 import { nowIso } from "../core/shared/time.js";
 import { listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { recordImprovementObservation, readImprovementLedger, } from "./improvement-ledger.js";
 import { projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, } from "./history-analytics.js";
@@ -210,9 +209,7 @@ function assembleStatsResult(totals, byType, byStatus, omittedZeroBuckets, optio
 /** Implements run stats for the public runtime surface of this module. */
 export async function runStats(global, options = {}) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const recordedObservations = await recordStatsObservations(global, options);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
@@ -271,4 +268,4 @@ export async function runStats(global, options = {}) {
     });
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=d28c7ac7-9801-5b0c-84c9-51deede398be
+//# debugId=b56db1fc-d989-5d18-8b29-336a03f1e525

package/dist/sdk/templates.js

@@ -4,7 +4,8 @@
  * Implements the pm templates 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]="f232e106-54f4-572e-8f6e-054f52290267")}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]="5c70da27-21f6-5d31-b506-96e1818996d6")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists, readFileIfExists, } from "../core/fs/fs-utils.js";
@@ -13,7 +14,7 @@ import { resolveAuthor } from "../core/shared/author.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { nowIso } from "../core/shared/time.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS } from "./cli-contracts.js";
 const TEMPLATE_DIRECTORY_NAME = "templates";
@@ -78,9 +79,7 @@ function templatePath(pmRoot, normalizedName) {
     return path.join(templatesDirectory(pmRoot), `${normalizedName}${TEMPLATE_FILE_EXTENSION}`);
 }
 async function ensureTrackerInitialized(pmRoot) {
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
 }
 function sortTemplateOptions(options) {
     return Object.fromEntries(Object.entries(options).sort(([left], [right]) => left.localeCompare(right)));
@@ -291,4 +290,4 @@ export async function runTemplatesShow(rawTemplateName, global) {
     };
 }
 //# sourceMappingURL=templates.js.map
-//# debugId=f232e106-54f4-572e-8f6e-054f52290267
+//# debugId=5c70da27-21f6-5d31-b506-96e1818996d6

package/dist/sdk/test/batch.js

@@ -4,8 +4,8 @@
  * 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]="7fea0ecb-35e2-5d40-931f-ffdd1a465fdc")}catch(e){}}();
-import { pathExists } from "../../core/fs/fs-utils.js";
+!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){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { parseOptionalNumber } from "../../core/item/parse.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 { getSettingsPath, 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";
@@ -421,9 +421,7 @@ const buildTestAllSelectionProgress = (params) => [
 /** Loads the tracker selection and linked tests for one test-all run. */
 const prepareTestAllRun = async (options, global) => {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const selection = await selectTestAllItems({ pmRoot, settings, options });
     const defaultTimeoutSeconds = parseTimeout(options.timeout);
@@ -489,4 +487,4 @@ export const _testOnlyTestAll = {
     formatTrackingError,
 };
 //# sourceMappingURL=batch.js.map
-//# debugId=7fea0ecb-35e2-5d40-931f-ffdd1a465fdc
+//# debugId=aeb0a1a7-bc73-5c56-bbed-9472c651b5f6

package/dist/sdk/test/execution.js

@@ -4,7 +4,8 @@
  * 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]="4322c352-6b95-5796-94eb-5a68745d53bc")}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]="2354c553-3a81-59d8-9c0a-3d19cd3cedd2")}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";
 import { tmpdir } from "node:os";
@@ -1849,9 +1850,7 @@ function buildTestMeasurementProjection(options, runs, recordedRun) {
 export async function runTest(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     if ((options.measure?.length ?? 0) > 0 && options.run !== true) {
         throw new PmCliError("--measure requires --run", EXIT_CODE.USAGE);
@@ -1965,4 +1964,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=4322c352-6b95-5796-94eb-5a68745d53bc
+//# debugId=2354c553-3a81-59d8-9c0a-3d19cd3cedd2

package/dist/sdk/test/runs.js

@@ -4,14 +4,14 @@
  * Implements the pm test runs 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]="8f02f498-5cee-59fa-9f4e-fd882c58d401")}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]="1cbb3565-26d8-5657-b724-602658bec852")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import os from "node:os";
-import { pathExists } from "../../core/fs/fs-utils.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { readAuthorEnvironment } from "../../core/shared/author.js";
 import { getBackgroundTestRunStatus, listBackgroundTestRuns, readBackgroundTestRunLogs, resumeBackgroundTestRun, runBackgroundTestRunWorker, spawnBackgroundTestRunWorker, startBackgroundTestRun, stopBackgroundTestRun, } from "../../core/test/background-runs.js";
-import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { parseLimit } from "../../core/shared/numeric-parsers.js";
 const BACKGROUND_STATUS_VALUES = [
@@ -81,9 +81,7 @@ function resolveRequestedBy(author, fallback) {
     return "unknown";
 }
 async function ensureInitialized(pmRoot) {
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
 }
 /** Implements run start background run for the public runtime surface of this module. */
 export async function runStartBackgroundRun(options, global) {
@@ -193,4 +191,4 @@ export async function runTestRunsWorker(runId, global) {
     };
 }
 //# sourceMappingURL=runs.js.map
-//# debugId=8f02f498-5cee-59fa-9f4e-fd882c58d401
+//# debugId=1cbb3565-26d8-5657-b724-602658bec852

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).
+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).
 
 These contracts keep common agent loops deterministic, token-efficient, and recoverable. Runtime contracts and `--help --json` remain the exact source for available flags.
 
@@ -10,6 +10,13 @@ These contracts keep common agent loops deterministic, token-efficient, and reco
 
 The public SDK exports `collectNewOrderingCycleWarnings(beforeItems, afterItems, changedItemId)` from `@unbrained/pm-cli/sdk`. Package authors can apply the same immutable-snapshot advisory to custom mutation workflows; activated custom relationship kinds participate through the shared registry.
 
+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.
+
 `pm graph audit` uses two explicit units:
 
 - `finding_count`, `findings_by_severity`, and `findings_by_code` count finding rows.

package/docs/COMMANDS.md

@@ -52,7 +52,7 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 | Family       | Commands                                                                                                                       | Purpose                                                                                                                                                                                                                                                |
 | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                        | create and inspect tracker setup                                                                                                                                                                                                                       |
-| Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state                                                                                                                                                                                                                                      |
+| 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                                                                                                                                                  |
@@ -165,6 +165,18 @@ custom statuses are normalized through the runtime status registry and an
 unknown status fails instead of returning a false-clean result.
 Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
+When the strongest duplicate match is terminal because the same work recurred,
+reuse its lineage instead of creating or copying another item:
+
+```bash
+pm item reopen pm-a1b2 "The production failure recurred" --status in_progress
+```
+
+The command appends a structured `reopen` history event, preserves the earlier
+closure in immutable history, clears stale terminal metadata through the normal
+update path, and refuses an already-active item. See
+[Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md).
+
 Add `--at <version|ISO-timestamp>` for a verified point-in-time read. It replays the same hash-checked history kernel used by restore but never acquires a lock, writes the item, or appends history. The result always includes `reconstructed: true`, `as_of_version`, and `as_of_timestamp`. Future/out-of-range targets fail with structured `valid_range` metadata. `--at` cannot be combined with `--tree`; workspace-wide historical graph projections require a future indexed primitive.
 `context` standard/deep views include high-level child completion counters plus `recently_created` and `unparented` sections, so agents can spot new orphan work before creating duplicates.
 Use `pm aggregate --completion` when you need per-group `open`, `in_progress`, `closed`, `other`, and `completion_pct` progress context.

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)
+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).
 
 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,6 +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.
 
+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
+`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
+`dependency_remove_no_match` and returns the unmatched selectors plus compact
+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.
+
 `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,
 not execution precedence. `supersedes` keeps replacement semantics, while

package/docs/README.md

@@ -57,6 +57,7 @@ pm guide release --json
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
 - [Defect Recurrence and Boundary Evidence](DEFECT_RECURRENCE.md) - captured external samples, structured defect-escape evidence, incremental change-risk indexing, and executable recovery-producer census.
+- [Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md) - terminal-item recurrence, duplicate-intake routing, capability-aware reindex recovery, and target-aware generated test guidance.
 - [Trustworthy Context and Evidence Contracts](TRUSTWORTHY_CONTEXT_EVIDENCE.md) - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.
 - [Context Integrity Contracts](CONTEXT_INTEGRITY_CONTRACTS.md) - sparse-read identity, closed extension manifests, lossless remote docs, direction-locked graph impact, and cross-version history epochs.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -0,0 +1,151 @@
+# Recurrence and Executable Recovery Contracts
+
+Tracked by [pm-83cz0o](../.agents/pm/features/pm-83cz0o.toon),
+[pm-qljv](../.agents/pm/issues/pm-qljv.toon),
+[pm-surv](../.agents/pm/issues/pm-surv.toon),
+[pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), and
+[pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon).
+
+## Agent Quick Context
+
+- Reuse an active matching item; reopen a terminal matching item.
+- `pm item reopen` is the noun-first recurrence command. It never creates a
+  second item and never rewrites the earlier close event.
+- Recovery guidance is capability-aware: it names an executable command on the
+  current surface, or installs the package that owns the command first.
+- Generated `AGENTS.md` guidance detects the target repository's test command.
+  When no executable test contract exists, it prints an explicit placeholder
+  instead of naming a pm-cli repository script that the target does not have.
+
+## Reopen Terminal Work
+
+```bash
+pm item reopen pm-a1b2 "The production failure recurred after deployment"
+pm item reopen pm-a1b2 "The customer reproduced the issue" --status in_progress
+```
+
+The command accepts only the workspace open or in-progress status. While
+holding the item lock it verifies that the current status is terminal, records
+one `reopen` history event with structured recurrence context, and delegates the
+state change to the normal update pipeline. Active metadata drops stale
+`closed_at`, `completed_at`, `close_reason`, `resolution`, `expected_result`,
+`actual_result`, and `fixed_version` values. Earlier history retains the exact
+closure values.
+
+Compact output keeps the recurrence receipt because the prior and next status,
+reason, and terminal evidence are the proof that this was a recurrence rather
+than a generic edit. An already-active item fails with
+`item_already_active` and points to `pm get <id> --full`; continue that item with
+`pm update` instead of manufacturing another recurrence event.
+
+## SDK and MCP
+
+```ts
+import { PmClient, reopen } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: "/workspace/.agents/pm" });
+const viaClient = await pm.reopen(
+  "pm-a1b2",
+  "The production failure recurred",
+  { status: "in_progress" },
+);
+
+const viaFunction = await reopen(
+  "pm-c3d4",
+  "The customer reproduced the issue",
+  {},
+  { pmRoot: "/workspace/.agents/pm" },
+);
+
+console.log(viaClient.recurrence.previous_terminal);
+console.log(viaFunction.recurrence.from_status);
+```
+
+Generic action hosts use `item-reopen` with required `id` and `reason` fields.
+The action participates in the generated action schema, SDK dispatch coverage,
+CLI/SDK parameter parity, command grammar, and MCP `pm_run` surface.
+
+## Tracker Preflight Recovery
+
+Every SDK command that requires project state now enters through one shared
+filesystem preflight instead of maintaining a command-local settings check.
+The public aggregate SDK exposes the same primitive for packages and embedded
+hosts:
+
+```ts
+import {
+  assertInitializedTracker,
+  assertReadableTrackerRoot,
+} from "@unbrained/pm-cli/sdk";
+
+await assertReadableTrackerRoot(candidateRoot); // an empty directory is valid
+await assertInitializedTracker(projectRoot); // settings.json is required
+```
+
+The refusal contract distinguishes four states before any command-specific
+read or mutation begins:
+
+| Selected root state | Code | Exit | Recovery |
+| --- | --- | ---: | --- |
+| Path does not exist | `tracker_root_missing` | 3 | Tokenized, non-interactive `pm --pm-path <path> init --defaults --agent-guidance skip` |
+| Directory exists but `settings.json` does not | `tracker_not_initialized` | 3 | The same initialization retry |
+| Path or ancestor is a regular file | `tracker_root_not_directory` | 2 | Select a directory; never suggest `pm init` against the file |
+| Directory cannot be read or searched | `tracker_root_unreadable` | 1 | Repair permissions, then retry the same selected root |
+
+`listTrackerPreflightRecoveryContracts` publishes this four-state corpus from
+`@unbrained/pm-cli/sdk/contracts`.
+`scoreTrackerPreflightRecoveryClosure` verifies code, exit class, recovery kind,
+and executable retry evidence. The repository recovery gate runs these probes
+beside the 18 closed-domain probes, so its ratcheted corpus is 22 and a removed
+state, failed retry, or unsafe file-path initialization suggestion blocks the
+release. The surface-replication gate separately requires at least 50 shared
+preflight invocations across the 45 migrated SDK modules and forbids the former
+inline error body from returning.
+
+## Duplicate Intake
+
+Create and copy similarity governance inspect all lifecycle statuses. The
+strongest active match returns a `pm get <id> --full` reuse path. The strongest
+terminal match returns:
+
+```bash
+pm item reopen <id> "<recurrence reason>"
+```
+
+Strict duplicate refusal exposes the same command and tokenized arguments in
+its structured recovery envelope. Advisory mode adds a compact
+`likely_duplicate_recovery:<reuse|reopen>:<id>` warning so agents can select the
+correct lifecycle action without reparsing prose.
+
+## Capability-Aware Reindex Recovery
+
+When semantic search detects stale vectors, it inspects the active extension
+command registry. If `reindex` is active, the direct recovery is:
+
+```bash
+pm reindex --mode hybrid
+```
+
+If the command is absent, recovery is a two-step executable sequence:
+
+```bash
+pm install search-advanced --project
+pm reindex --mode hybrid
+```
+
+The human warning and structured `vector_index_recovery` tokens come from the
+same resolution. This prevents a base installation from suggesting an
+unavailable command.
+
+## Target-Aware Generated Test Guidance
+
+`pm init --agent-guidance add` resolves the linked-test command in this order:
+
+1. `node scripts/run-tests.mjs test` when that repository script exists.
+2. The declared package manager's `test` script (`pnpm test`, `bun run test`,
+   `yarn test`, or `npm test`).
+3. `<your project test command>` when the target does not declare an executable
+   test contract.
+
+The managed guidance block is versioned, so a later init can replace an older
+pm-managed block without changing surrounding repository instructions.