@unbrained/pm-cli 2026.8.18 → 2026.8.20

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="48d9b905-70a1-52c3-9b9c-33624661e6eb")}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]="c770afea-3eb6-5476-ba07-8ec1c5d9c699")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -70,6 +70,7 @@ import { acknowledgeUnknownAuthorHistoryEventsFromTransport, } from "./author-at
 import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, runProfileShow, } from "./profile.js";
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
+import { runMcpCloseAction, runMcpReopenAction } from "./lifecycle/mcp-actions.js";
 import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
@@ -119,6 +120,7 @@ export { runFocus, } from "./lifecycle/focus.js";
 export { runRestore, } from "./lifecycle/restore.js";
 export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, } from "./lifecycle-policy.js";
 export { runUpdate } from "./lifecycle/update.js";
+export { runReopen } from "./lifecycle/reopen.js";
 export { NEXT_OUTPUT_VALUES, runNext, } from "./query/next.js";
 export { runSearch, } from "./query/search.js";
 export { runStats, } from "./stats.js";
@@ -536,6 +538,15 @@ export class PmClient {
             ...splitFullClientMutationOptions(options),
         });
     }
+    /** Reopen terminal work as a recurrence through the canonical update path. */
+    reopen(id, reason, options = {}) {
+        return this.runTyped("item-reopen", {
+            id,
+            reason,
+            fullChangedFields: true,
+            options,
+        });
+    }
     /** Close an item using the same mutation path as `pm close`. Options are contract-typed (pm-x29o); the close reason is the positional parameter, so the option bag omits `reason`/`text`. */
     close(id, reason, options = {}) {
         return this.runTyped("close", {
@@ -908,6 +919,10 @@ export function create(options = {}, clientOptions = {}) {
 export function update(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).update(id, options);
 }
+/** Reopen terminal work as a recurrence without constructing a reusable client. */
+export function reopen(id, reason, options = {}, clientOptions = {}) {
+    return new PmClient(clientOptions).reopen(id, reason, options);
+}
 /** Close an item without constructing a reusable client. */
 export function close(id, reason, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).close(id, reason, options);
@@ -1349,13 +1364,14 @@ async function runMcpListAction(ctx) {
     return withQuerySummary((await runList(readString(ctx.args, "status") ?? readString(listOptions, "status"), listOptions, ctx.global)), listOptions);
 }
 async function runMcpSearchAction(ctx) {
-    const searchOptions = applyContextIntentProjection("search", ctx.options);
+    const query = readRequiredString(ctx.args, "query");
+    const searchOptions = applyContextIntentProjection("search", ctx.options, [query]);
     if (searchOptions.compact === undefined &&
         searchOptions.full === undefined &&
         searchOptions.fields === undefined) {
         searchOptions.compact = true;
     }
-    return withQuerySummary((await runSearch(readRequiredString(ctx.args, "query"), searchOptions, ctx.global)), searchOptions);
+    return withQuerySummary((await runSearch(query, searchOptions, ctx.global)), searchOptions);
 }
 async function runMcpCreateAction(ctx) {
     const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
@@ -1391,18 +1407,6 @@ async function runMcpUpdateAction(ctx) {
         idOnly,
     });
 }
-async function runMcpCloseAction(ctx) {
-    const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
-    const closeReason = readString(ctx.args, "reason") ??
-        readString(ctx.args, "text") ??
-        readString(runnerOptions, "reason") ??
-        readString(runnerOptions, "text");
-    return projectMutationResult(await runClose(requireMcpItemId(ctx, runnerOptions), closeReason, runnerOptions, ctx.global), {
-        changedFields,
-        compactEnvelope: changedFields === "compact" && !idOnly,
-        idOnly,
-    });
-}
 function runMcpCommentsAction(ctx) {
     const commentOptions = normalizeAnnotationTransportOptions(ctx.options);
     const isListing = commentOptions.add === undefined &&
@@ -1783,7 +1787,10 @@ const SDK_ACTION_HANDLERS = {
     event: runRuntimeSchedulingAction,
     remind: runRuntimeSchedulingAction,
     list: runMcpListAction,
-    get: (ctx) => runGet(requireMcpItemId(ctx), ctx.global, applyContextIntentProjection("get", ctx.options)),
+    get: (ctx) => {
+        const id = requireMcpItemId(ctx);
+        return runGet(id, ctx.global, applyContextIntentProjection("get", ctx.options, [id]));
+    },
     search: runMcpSearchAction,
     duplicates: (ctx) => {
         const status = typeof ctx.options.status === "string"
@@ -1804,6 +1811,7 @@ const SDK_ACTION_HANDLERS = {
     copy: runMcpCopyAction,
     focus: (ctx) => runFocus(ctx.id, { clear: ctx.options.clear === true || ctx.args.clear === true }, ctx.global),
     update: runMcpUpdateAction,
+    "item-reopen": runMcpReopenAction,
     restore: runMcpRestoreAction,
     claim: (ctx) => ctx.options.next === true || ctx.args.next === true
         ? runClaimNext(ctx.force, ctx.global, { ...ctx.options, ...ctx.args }, { ...ctx.options, ...ctx.args })
@@ -1936,4 +1944,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=48d9b905-70a1-52c3-9b9c-33624661e6eb
+//# debugId=c770afea-3eb6-5476-ba07-8ec1c5d9c699

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/workspace-snapshot.d.ts

@@ -1,5 +1,7 @@
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export declare const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
+/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
+export declare const WORKSPACE_SNAPSHOT_ACTIONS: readonly ["create", "list", "inspect", "restore", "delete"];
 /** Filesystem operations required by atomic snapshot publish and restore swaps. */
 export interface WorkspaceSnapshotAtomicOperations {
     /** Rename one filesystem entry atomically. */

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="36aacc71-c5f5-56f1-85f4-28b2be5b02e2")}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]="2580e043-8675-5070-b57e-30cae333228c")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -18,6 +18,14 @@ import { PmCliError } from "../core/shared/errors.js";
 import { withHostEnvironmentBoundary } from "./environment/host-environment-errors.js";
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
+/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
+export const WORKSPACE_SNAPSHOT_ACTIONS = [
+    "create",
+    "list",
+    "inspect",
+    "restore",
+    "delete",
+];
 const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
 const EXCLUDED_ROOT_NAMES = new Set([
     "checkpoints",
@@ -603,4 +611,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=36aacc71-c5f5-56f1-85f4-28b2be5b02e2
+//# debugId=2580e043-8675-5070-b57e-30cae333228c

package/docs/COMMANDS.md

@@ -2,7 +2,7 @@
 
 This is a task-oriented command guide. For exact flags, use runtime help because extensions and settings can change the active surface:
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), positional action discovery [pm-2tan](../.agents/pm/issues/pm-2tan.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
 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).
 
@@ -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.
@@ -1120,6 +1132,13 @@ Profiles are extensible: a package can ship its own archetype with `api.register
 
 Plan creation shares the normal create contract. Governance fields such as `--status`, `--deadline`, `--estimate`, `--acceptance-criteria`, `--assignee`, review/risk fields, comments, notes, learnings, reminders, events, and linked resources are accepted directly and pass through the same strict/progressive schema validation as `pm create`.
 
+Every positional plan action is also a discoverable virtual command path. Use
+`pm plan create --help --json` or `pm help plan create --json` for its exact
+arguments and effective flags, and use `pm contracts --command "plan create"
+--flags-only --json` for the matching machine contract. Root `pm plan --help
+--json` publishes the same action inventory under `subcommands`; omitting the
+required action fails as `missing_required_argument` before mutation dispatch.
+
 ```bash
 pm plan create --title "Refactor lock retry" --scope "Improve retry semantics" --harness claude-code --parent pm-epic1 --related pm-rel1,pm-rel2 --claim
 pm plan create --title "Fix flaky retry test" --step "Read lock.ts" --step "Write the fix" --step "Run the tests"
@@ -1190,9 +1209,14 @@ Project-governance setters use the separate `governance_contracts` value
 domains; in particular, workflow enforcement is `off|warn|strict`, not the
 extension policy token `enforce`.
 Use `pm contracts --summary --json` first when bootstrapping in a tight context
-window. `command_summaries` contains exactly one row per advertised command
-path—including aliases and namespace children—with a meaningful intent plus
-`default_max_estimated_tokens` and the format-specific TOON/JSON ceilings.
+window. `command_summaries` contains one row per registered command path,
+including aliases and namespace children, with a meaningful intent plus
+`default_max_estimated_tokens`. The low-token summary intentionally does not
+repeat the 32 virtual positional Plan, Assurance, and workspace-snapshot action rows;
+`grammar_contracts.positional_action_count` and `positional_action_parents`
+retain their complete discoverability and route callers to root help. A
+command-scoped contract for an exact action restores its typed positional
+signature, exact flags, provenance, and format-specific TOON/JSON ceilings.
 Package commands contribute their intent through command registration (falling
 back to the registered description), so agents never need a generic
 `Inspect flags.` placeholder. Request heavier command-specific flags or schemas

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -15,7 +15,8 @@ selectors are tracked by
 [pm-x710qm](../.agents/pm/issues/pm-x710qm.toon). Default contract suppression
 and canonical TOON tables are tracked by
 [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
-[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon).
+[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon). Nested evidence continuation
+is tracked by [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon).
 
 ## Agent Quick Context
 
@@ -73,6 +74,7 @@ or not the current page has rows:
     "command": "list",
     "row_kind": "collection",
     "row_keys": ["items"],
+    "continuation_row_keys": ["items"],
     "fields": "supported",
     "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end",
     "toon_encoding": "tabular_when_uniform"
@@ -89,6 +91,12 @@ nested dependency graph and relationship-context rows addressable as
 `graph.nodes`, `graph.edges`, `context.nodes`, and `context.edges` without
 duplicating them at the envelope root. Array collections produce their
 elements; object maps produce jq `to_entries` rows.
+`continuation_row_keys` is optional and defaults to `row_keys`. A command uses
+it only when independently resumable nested evidence differs from its primary
+amount-bounded rows. Validate, for example, keeps `checks` and `warnings` as
+primary rows while a rich result can name
+`checks.0.details.missing_resolution_rows` as a continuation row. This prevents
+an inner diagnostic array from disabling `--output-limit` on the outer checks.
 `toon_encoding: "tabular_when_uniform"` declares that an array of flat objects
 with one shared key set renders as a length-marked TOON table; mixed, nested,
 or heterogeneous arrays retain the expanded representation. Quoted,
@@ -107,7 +115,8 @@ publish a row contract.
 SDK and package authors can import `PM_READ_ROW_CONTRACTS`,
 `PM_READ_ROW_JQ_SELECTOR`, and `resolveReadRowContract` from
 `@unbrained/pm-cli/sdk`. Existing package declarations are preserved only
-when `command`, `row_kind`, `row_keys`, `fields`, the conditional
+when `command`, `row_kind`, `row_keys`, optional unique non-empty
+`continuation_row_keys`, `fields`, the conditional
 `jq_selector`, and any supplied `toon_encoding` form a structurally valid row contract; malformed declarations
 are replaced by the canonical built-in contract when one applies.
 

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

@@ -15,10 +15,13 @@ Every built-in read surface uses four output dimensions: what to include, how mu
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
-Row shaping follows each envelope's `row_contract.row_keys`, including
-dot-delimited nested arrays and object maps such as `graph.nodes`. Include,
-amount, repeat suppression, and cost compaction therefore operate on the same
-machine-declared rows; they do not rely on command-specific top-level keys.
+Primary row shaping follows each envelope's `row_contract.row_keys`, including
+dot-delimited arrays and object maps such as `graph.nodes`. Include, amount, and
+repeat suppression therefore remain bound to the rows the command says it
+returns. A result may additionally declare `continuation_row_keys` when a
+nested evidence collection must resume independently without redefining the
+primary rows that `--output-limit` bounds. Cost compaction may inspect both
+primary and nested collections; it does not rely on command-specific keys.
 The runtime uses that declaration internally on every read but omits the
 repeated metadata from results by default. Request
 `--output-row-contract` / `outputRowContract: true` when a consumer needs the
@@ -153,8 +156,9 @@ producer cursor, a universal output cursor, and a terminal page;
 `next_cursor` mirrors the first universal entry for ordinary one-path
 consumers. Replay the same query and budget
 with `--output-cursor <cursor>` / `outputCursor`. The cursor validates the
-command, declared row path, total, and stable row identities before slicing, so
-a mismatched or stale replay fails closed instead of skipping evidence. A
+command, declared continuation path, total, and canonical content fingerprint
+before slicing, so same-cardinality content changes and other stale replays
+fail closed instead of skipping evidence. A
 bounded recovery therefore does not require replacing a 600-token request with
 an unbounded multi-megabyte response;
 `recovery_budget_multiplier: 1` declares that each next page retains the same

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -0,0 +1,114 @@
+# 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.
+
+## 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.

package/docs/SDK.md

@@ -50,6 +50,15 @@ first-class recurrence relationships are tracked by
 Fail-closed whole-corpus reads and package-catalog output controls are tracked by
 [pm-y4aaol](../.agents/pm/issues/pm-y4aaol.toon) and
 [pm-2firut](../.agents/pm/issues/pm-2firut.toon).
+Positional command signatures, action-scoped discovery, and MCP/CLI option
+parity are tracked by [pm-ya7x55](../.agents/pm/tasks/pm-ya7x55.toon),
+[pm-2tan](../.agents/pm/issues/pm-2tan.toon), and
+[pm-y0htkd](../.agents/pm/issues/pm-y0htkd.toon).
+Terminal recurrence and executable recovery are tracked by
+[pm-83cz0o](../.agents/pm/features/pm-83cz0o.toon),
+[pm-qljv](../.agents/pm/issues/pm-qljv.toon), and
+[pm-surv](../.agents/pm/issues/pm-surv.toon); see
+[Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md).
 
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
@@ -340,6 +349,8 @@ Command/action contract exports:
 - Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
 - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
 - Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry`, `resolveMissingOptionPlaceholder`, and `resolveRecoveryCommandName` preserve attempted argv, derive enum/boolean/scalar recovery arity from flag contracts, and identify the actual command without mistaking a global option value for one; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Positional grammar primitives: `PM_COMMAND_POSITIONAL_CONTRACTS` declares every core and known-package command signature as ordered, typed slots; `PM_POSITIONAL_ACTION_CONTRACTS` promotes positional plan and assurance actions into discoverable virtual command paths with action-scoped flags, examples, and intent. `resolvePmCommandPositionalContract`, `resolvePmPositionalActionContract`, and `verifyPmCommandPositionalContracts` let custom hosts resolve or fail-closed compare the same signatures emitted by runtime contracts. The grammar receipt ratchets distinct semantic shapes through `positional_shape_budget` so a new arity cannot silently expand agent context.
+- MCP/CLI option parity primitive: `verifyToolOptionCliParity` compares one `ToolOptionFlagContract` table with its executable `CliFlagContract` table. It fails when the transport-selected canonical flag is absent or when a parameter such as `linkedFile` cannot be invoked using its kebab-case CLI spelling (`--linked-file`) canonically or through a registered alias. Core create/update parity is part of the required command-grammar gate.
 - Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
@@ -1121,10 +1132,13 @@ filters, and bound the race-loss candidate walk with `maxAttempts` (1 through
 tools do not need to reproduce CLI concurrency policy.
 
 Lifecycle convenience methods and the matching top-level functions (`create`,
-`update`, `close`, `claim`, `release`, `copy`, `deleteItem`, `restore`,
+`update`, `reopen`, `close`, `claim`, `release`, `copy`, `deleteItem`, `restore`,
 `focus`, `startTask`, `pauseTask`, and `closeTask`) use the same mutation paths
 as the CLI and MCP dispatcher. They are the baseline primitives for custom PM
-tools that need to own item state without spawning `pm`.
+tools that need to own item state without spawning `pm`. `reopen` requires a
+recurrence reason, accepts only the workspace open or in-progress target, and
+returns the terminal evidence captured atomically before the update path clears
+it from active metadata.
 
 ### Atomic workspace transactions