@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/docs/AGENT_GUIDE.md

@@ -109,8 +109,9 @@ pm close <item-id> "Acceptance criteria met; verification passed." --resolution
 pm release <item-id>
 ```
 
-If a warning close omitted evidence, use its `recovery.suggested_retry_args`
-to append an evidence update while preserving the original close event. See
+If a successful warning close omitted evidence, use its `follow_up.suggested_command_args`
+to append an evidence update while preserving the original close event. Failed closes
+retain `recovery.suggested_retry_args`. See
 [Close Evidence Recovery](CLOSE_EVIDENCE_RECOVERY.md).
 
 For real subprocess tests, set `cwd`, `PM_PATH`, and `PM_GLOBAL_PATH` to the
@@ -180,6 +181,10 @@ Over MCP the mutation tools (`pm_create`/`pm_update`/`pm_append`/`pm_close`, and
 
 `pm create --parent <id>` fails fast when the parent cannot be found. Use `--allow-missing-parent` only for deliberate imports or staged backlog reconstruction.
 
+To record many items at once (triage imports, review-thread capture, plan expansion), do not loop `pm create`: write one record per line and commit them in one workspace transaction with `pm item mutate --from items.jsonl --json` (`--dry-run` first). Records use `pm create` field names, `@row-<n>`/`@ref` references link records to each other, and `--upsert-key <field>` turns records that match an existing item into updates. `pm create many` refuses with this route.
+
+The default transaction id derives from the exact document bytes, so even a formatting-only edit selects a new id. To replay a committed import, reuse its transaction id and keep the resolved mutation plan unchanged. For formatting-only edits, pass the original id explicitly with `--transaction-id <id>`; replay still requires the same resolved plan. See [Bulk creation](COMMANDS.md#bulk-creation-pm-create-many-route).
+
 ## Guide Routing for Agents
 
 Use the canonical [guide topic map](README.md#guide-topic-map) when local in-CLI documentation routing is useful.
@@ -187,10 +192,34 @@ Use the canonical [guide topic map](README.md#guide-topic-map) when local in-CLI
 ## Ownership Rules
 
 - Claim before heavy edits.
-- `pm claim <id>` can take over non-terminal work from another owner.
-- Use `--force` only for explicit override paths.
+- `pm claim <id>` is an atomic test-and-set. A non-terminal item already held by a different principal refuses with `already_claimed_by`; the same principal re-claiming is a no-op.
+- Pass `--if-available` to treat a held item as a skip (`skipped: true`, exit 0) instead of a failure, for example when several agents pull from one queue. The terminal check runs first, so a terminal item still refuses without `--force` even when `--if-available` is set.
+- Use `--force` only for a coordinated takeover of another owner's claim; it is also required to claim terminal items, and to override stale locks when the `governance.force_required_for_stale_lock` policy is enabled (the `minimal` and custom governance presets can disable it). Never force a takeover without explicit approval.
 - Release when pausing, handing off, or after close.
 
+### Implementation-to-verification handoff
+
+Tracked by [pm-gh1465](../.agents/pm/features/pm-gh1465.toon).
+Projects define their own queues using the existing schema primitives:
+
+```bash
+pm schema add-status review --role active --description "Implementation complete; awaiting verification"
+pm release <item-id> --handoff review --message "Implemented X; verify with the linked regression"
+pm list --status review
+```
+
+Handoff requires a claimed, non-terminal item and an evidence message. It changes
+the status and releases ownership in one history event, preserving workflow
+transition and approval policies. It cannot be combined with `--pause` or target
+the configured in-progress or a terminal status. The result includes `handoff`
+with the source status, destination status, and evidence message. No fixed review
+state is added to projects. `pm context` retains the queue's status while counting
+it separately from in-progress work; use `pm list --status review` to select the
+verification queue. A verifier can claim it, close with normal evidence, or use
+`pm claim <item-id> --start` when rework begins. `pm item reopen` remains for
+terminal items. SDK `client.release(id, { handoff: "review", message: "..." })`
+and MCP release options use the same atomic transition.
+
 ## Reviewed Delivery Closeout
 
 Before closing repository defects, set `escape_class` and structured

package/docs/CLOSE_EVIDENCE_RECOVERY.md

@@ -1,13 +1,15 @@
 # Recovering missing close evidence
 
-Tracked by [pm-ub1ott](../.agents/pm/issues/pm-ub1ott.toon).
+Tracked by [pm-ub1ott](../.agents/pm/issues/pm-ub1ott.toon) and
+[pm-gh1464](../.agents/pm/issues/pm-gh1464.toon).
 
 `pm close --validate-close warn` can close an item while reporting missing
 resolution, expected outcome, or actual outcome. Its SDK result and compact CLI
-output now include `recovery.missing`, `suggested_retry`, and
-`suggested_retry_args` when evidence is incomplete. The argument vector selects
+output include an optional `follow_up` with `kind: complete_close_evidence`,
+`missing`, `suggested_command`, and `suggested_command_args` when evidence is
+incomplete. The close succeeded; do not retry it. The argument vector selects
 the same tracker and uses `pm update` to add only the missing evidence fields.
-Use `recovery.suggested_retry_args` as the authoritative argument vector. Replace
+Use `follow_up.suggested_command_args` as the authoritative argument vector. Replace
 each `<value>` with the observed outcome before executing it; retain its tracker
 selection and only the flags it supplies for missing fields. Do not add flags
 for evidence already present, because `pm update` would overwrite that evidence.
@@ -25,11 +27,18 @@ recovery when applicable. `--force` is reserved for an intentional repeated
 lifecycle transition. Adding evidence with `pm update` preserves the original
 close timestamp, close reason, and immutable history event, then appends a
 normal update event. It does not retroactively claim that evidence existed at
-the original close. Complete closes have no extra recovery payload.
+the original close. Failed terminal retries retain `recovery.suggested_retry_args`;
+successful closes never emit failure recovery. Complete closes have no follow-up.
 
 The update flags for the other missing fields are `--resolution` and
 `--expected-result`; include them only when the generated recovery requests them.
 
 For new work, include all three fields in the original close command so its
-immutable event contains the full evidence. Warning-mode recovery exists for
-incomplete historical or interrupted workflows.
+immutable event contains the full evidence:
+
+```bash
+pm close <item-id> "Delivered and verified" --resolution "What changed" \
+  --expected "Required outcome" --actual "Observed outcome" --validate-close warn
+```
+
+Warning-mode follow-up exists for incomplete historical or interrupted workflows.

package/docs/COMMANDS.md

@@ -336,14 +336,23 @@ pm eval --fail-under 0.6 --json      # CI gate: exit non-zero when aggregate nDC
 
 ### Full results, totals, and bodies
 
-`pm list` returns every matched row when neither `--limit` nor `--offset` is set. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. `completeness` reports whether the corpus was `complete`, `partial`, or `unchecked` (derived-index page), with unreadable item/directory counts. Use `--strict-read` when omissions must fail the command. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` to force the entire matched set and override any `--limit` in one call. `--all` selects every lifecycle status; combine the flags for an unbounded all-status audit:
+`pm list` selects every matched row when neither `--limit` nor `--offset` is set; the default output budget can still bound delivery. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. `completeness` reports whether the corpus was `complete`, `partial`, or `unchecked` (derived-index page), with unreadable item/directory counts. Use `--strict-read` when omissions must fail the command. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` to disable the default output budget; an explicit `--limit` still caps rows, and an explicit `--output-budget` still applies. `--all` selects every lifecycle status; combine the flags for an unbounded all-status audit:
 
 ```bash
-pm list --all --no-truncate --brief        # every matched row, ignoring any --limit
+pm list --all --no-truncate --brief        # every matched row without the default token ceiling
 pm list --status open --limit 20 --json    # stable total/has_more/truncated/next_cursor envelope
 pm list --all --strict-read --json         # fail if any source item cannot be read
 ```
 
+Continuation recovery is tracked by [pm-gh1457](../.agents/pm/issues/pm-gh1457.toon).
+For list, search and context, pass a producer `next_cursor` to `--after`.
+When `continuation_kind=output_cursor` is present, consume `next_cursor` through
+`--output-cursor` instead. An output continuation resumes within the same
+producer page, so retain its original query and any producer `--after` value.
+Passing an output cursor to `--after` returns `invalid_query_cursor` with the
+executable flag substitution in `next_steps`. Changed filters or snapshots
+still refuse rather than silently restarting.
+
 Compatibility note: older responses emitted `total` only when pagination
 omitted rows, omitted `next_cursor` on a completed page, and emitted unset
 verbose filter keys as `null`. Integrations should now read `total` as the
@@ -611,14 +620,19 @@ row summaries. See tracker item [pm-awe3t6](../.agents/pm/issues/pm-awe3t6.toon)
 Tracked by [pm-o8z748](../.agents/pm/issues/pm-o8z748.toon) and
 [pm-cyn0y6](../.agents/pm/issues/pm-cyn0y6.toon).
 
-`pm item mutate` is the noun-first CLI adapter over the public SDK resolver and
-`commitItemMutations` primitive. Pipe either the legacy non-empty JSON array or
-a versioned `{ "schema_version": 1, "mutations": [...] }` document, provide one
-stable transaction id, and mix create/update/close/release operations in order.
-Create rows may declare a unique `ref` and omit `id`; exact `@ref` values work
-in target ids, `parent`, `blockedBy`, and dependency `id` fields. The resolver
-derives replay-stable ids before the writer lock and returns a `references`
-receipt:
+`pm item mutate` is the noun-first CLI adapter over the public SDK planner
+(`planItemMutationDocument`) and `commitItemMutations` primitive. Pipe either
+the legacy non-empty JSON array, a versioned
+`{ "schema_version": 1, "mutations": [...] }` document, or JSON Lines (one
+record per line), or read any of them from a file with `--from <path>`. Mix
+create/update/close/release operations in order. Create rows may declare a
+unique `ref` and omit `id`; exact `@ref` values work in target ids, `parent`,
+`blockedBy`, and dependency `id` fields. The resolver derives replay-stable ids
+before the writer lock and returns a `references` receipt plus an input-ordered
+`rows` receipt (`index`, `ref`, `id`, `op`, `upserted`). When `--transaction-id`
+is omitted the id is derived from the exact document bytes
+(`transaction_id_source: "derived"`), so identical bytes select the same
+journal. Replaying a committed import also requires an unchanged resolved plan:
 
 ```bash
 pm item mutate \
@@ -635,13 +649,83 @@ pm item mutate \
 JSON
 ```
 
+`--from <path>` selects a file and rejects an explicitly supplied `--stdin-json`.
+Default stdin input, explicit `--stdin-json` without a file, and `--from -`
+remain supported.
+
 Use `--dry-run` to validate and preview without acquiring a writer lock. Reuse
 the exact transaction id and deterministic batch after interruption: the SDK
 journal resumes pending steps and never duplicates a successfully applied
-step. `--create-compensation close|delete`, `--lock-ttl-seconds`, and
-`--lock-wait-ms` expose the transaction safety controls. The equivalent MCP
+step. A different plan under a committed or resumable journal refuses with
+`transaction_plan_mismatch`; pass a new `--transaction-id` to commit that changed
+plan as its own transaction. A fully compensated attempt has nothing left to
+resume and may accept a new plan under the same transaction id. Formatting-only
+edits change a derived id; pass the original id explicitly to replay them when
+the resolved plan is unchanged. `--create-compensation close|delete`,
+`--lock-ttl-seconds`, and `--lock-wait-ms` expose the transaction safety controls. The equivalent MCP
 surface is `pm_mutate`.
 
+Raw mutation `options` use command option types: write `estimatedMinutes: "45"`.
+Item documents may instead use numeric `estimated_minutes: 45`. A non-string
+raw estimate refuses before journal or item writes with
+`mutation_option_value_invalid` (exit 2), identifying the row and option.
+Corrupt durable journals, including a wrong stored schema version or transaction
+identity, refuse with `transaction_journal_invalid`; preserve
+the journal and inspect or restore verified state before retrying. Changing the
+transaction id does not safely recover unknown previously applied work.
+
+#### Bulk creation (`pm create many` route)
+
+Tracked by [pm-gh1456](../.agents/pm/features/pm-gh1456.toon). `pm create many`
+is not a command; it refuses with `bulk_create_route` and points here. A record
+without `op` is a create document that uses the same field names as
+`pm create` flags or their JSON equivalents (`title`, `type`, `description`,
+`body`, `tags`, `parent`, `priority`, declared custom fields, ...); a create
+row may also carry that document under `item` instead of `options`. Records
+without `ref` or `id` receive `row-<n>` aliases so the receipt and `@row-<n>`
+references stay addressable. One process, one workspace transaction: every
+record is created or none.
+
+```bash
+cat > items.jsonl <<'JSONL'
+{"title":"Imported A","type":"Task","external_id":"ext-1","tags":["import"]}
+{"ref":"b","title":"Imported B","type":"Feature","external_id":"ext-2","parent":"@row-1"}
+JSONL
+pm item mutate --from items.jsonl --dry-run --json   # validate, derived transaction id
+pm item mutate --from items.jsonl --json             # commit; re-running replays (recovered: true)
+```
+
+`--upsert-key <field>` makes a re-run safe for changed data: a create record
+whose field value matches exactly one existing item (core field such as
+`title`, or a declared custom field such as `external_id`) becomes an update
+of that item and is reported with `upserted: true`. Matching and lock-held
+guards use the field's stored metadata key; core option names such as
+`acceptanceCriteria`, declared field keys and their SDK option targets
+(for example `externalId`) resolve to that
+same stored key. The record keeps its
+`ref` in the receipt, and later records may still address it as `@ref`, which
+then resolves to the matched item. A record missing the key, two records
+sharing a key value, or a key value matching several existing items refuses
+before any write (`upsert_key_missing`, `upsert_key_duplicate`,
+`upsert_key_ambiguous`). Matching happens before the writer lock, so every
+record that matched nothing carries its key into the commit, which re-checks
+it under the lock: when another writer created an item with that key value
+after planning, the transaction refuses with `upsert_key_conflict` before any
+write, and a re-run plans the record as an update of that item. A record that
+did match is committed as an update that re-reads the key under the lock and
+refuses with `upsert_match_changed` when the key was changed or removed after
+planning. Either refusal rolls the attempt back completely, and a rolled-back
+attempt leaves its derived transaction id reusable, so re-running the same
+document simply starts a fresh attempt from the current key values.
+
+```bash
+printf '%s\n' '{"title":"Imported A (renamed)","type":"Task","external_id":"ext-1"}' \
+  | pm item mutate --upsert-key external_id --json
+```
+
+Over MCP, `pm_mutate` accepts the same document rows as `{ref?, item: {...}}`
+entries, `upsertKey`, and an optional `transactionId`.
+
 `pm item complete` composes evidence, governed closure, and claim release into
 one compensating SDK transaction. It accepts the normal repeatable evidence
 flags and can preview the exact ordered mutations before writing:

package/docs/ECOSYSTEM_PLANNING_REVIEW.md

@@ -27,12 +27,16 @@ it is not silently equated with the earlier item snapshot. History-drift
 validation passed across all 2,826 current items. The public SDK independently
 verified hash chains for all 2,841 collected streams with zero failures.
 
-[The per-item census](ecosystem-review-2026-09-28.json) records every snapshot
+[The per-item census](https://github.com/unbraind/pm-cli/blob/main/docs/ecosystem-review-2026-09-28.json) records every snapshot
 ID, status, content fingerprint, structural classification, missing planning
 fields, historical evidence gaps, and remediation owner. These are mechanical
 findings, not invented historical estimates, outcomes, or review approvals.
 The full raw corpus stays outside public documentation.
 
+The census is intentionally excluded from npm. This packaged page uses its
+canonical GitHub file URL under the [documentation policy](../AGENTS.md#documentation-policy),
+so installed readers can access the data without a broken package-relative path.
+
 | Measure | Initial observation | Interpretation |
 | --- | ---: | --- |
 | Directed graph edges | 14,097 | Deduplicated directed basis |

package/docs/EXTENSIONS.md

@@ -305,7 +305,7 @@ Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
 
 - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
 - `api.registerCommand(definition)` adds package-owned commands; `read_output` opts readers into the [SDK output contract](SDK.md#minimal-command-extension).
-- `api.registerFlags(command, flags)` adds runtime command flags. A flag may declare `value_type` (canonical; the legacy `type` alias is honored only when `value_type` is absent), `list: true` to accumulate repeated/comma-joined values like core `--tags`, and a `default` applied when the flag is omitted.
+- `api.registerFlags(command, flags)` adds runtime command flags. A flag may declare `value_type` (canonical; the legacy `type` alias is honored only when `value_type` is absent), `list: true` to accumulate repeated/comma-joined values like core `--tags`, a `default` applied when the flag is omitted, and `value_validation: "strict"` to refuse malformed `number`/`boolean` tokens before the handler runs (the default `"coerce"` forwards the raw token). See [Flag Contracts](SDK.md#flag-contracts).
 - `api.registerItemFields(fields)` adds custom metadata fields. Agents can set declared fields with repeatable `pm create --field name=value` and `pm update <id> --field name=value`; undeclared names are rejected. `SchemaFieldDefinition.type` is the same closed union used by `pm schema add-field`: `string | number | boolean | string_array | array | object`. Unsupported values fail at compile time for TypeScript authors and at activation for JavaScript packages, with a did-you-mean hint on typos. `string_array` is the repeatable string collection; `array` and `object` require JSON containers.
 - Custom fields whose camel-case option name is already owned by a canonical MCP input remain usable through `options.<name>`, but authoring surfaces report the collision instead of allowing silent top-level shadowing. `pm schema add-field`, `pm profile lint`, and `pm package doctor` name the field, canonical `mcp_tool_input` owner, and nested recovery path. SDK authors can preflight the same rule with `resolvePmToolCustomFieldCollision`.
 - `api.registerItemTypes(types)` adds custom item types.

package/docs/EXTENSION_AUTHOR_CONTRACTS.md

@@ -8,14 +8,28 @@ This page records runtime contracts package authors need when they build on the
 
 Tracked by [pm-gh1461](../.agents/pm/issues/pm-gh1461.toon) and
 [pm-gh1462](../.agents/pm/features/pm-gh1462.toon).
+Value grammar corrections are tracked by [pm-gh1466](../.agents/pm/issues/pm-gh1466.toon)
+and [pm-gh1467](../.agents/pm/issues/pm-gh1467.toon).
 Prefer `{ long: "--repo", value_name: "project", value_type: "string" }`.
 Legacy `--repo <project>`, `--repo=<project>` and `--label [name]` declarations
 retain one canonical identity, one value placeholder and one help listing.
 Optional brackets permit presence without a value. Explicit `value_name` wins
-over the inline label, and boolean types remain value-free. Runtime contracts
-omit inferred labels for boolean flags, including legacy dynamic `bool` aliases;
-explicit legacy `value_name` metadata remains compatible. The SDK owns the
-canonical long-name rule used by help, option dispatch and contract discovery.
+over the inline label. Canonical `boolean` flags are switches, including when an
+inline label is present. Legacy `bool` declarations retain their value grammar:
+`--enabled false`, `--enabled 0`, and their short forms consume and coerce the
+value. A bare legacy `bool` permits presence without a value, preserving the
+published switch form too. An explicit `--enabled <value>` still requires its
+operand; `--enabled [value]` permits omission. A canonical
+boolean switch leaves subsequent positional values intact. Existing equals and
+negated forms remain supported; loose negated flags remain in `context.args`.
+Use `--` to distinguish a positional operand immediately after an optional-valued
+legacy `bool`, for example `--enabled -- operand`.
+The SDK's explicit `value_arity` distinguishes `none`, `required`, and `optional`
+from the scalar `value_type`. `required` describes flag presence: an optional
+value remains optional even when the flag itself is required. Help, Commander,
+recovery and machine contracts consume the shared SDK value declaration.
+Explicit legacy `value_name` metadata remains discoverable on switches for
+compatibility; `value_arity: "none"` still means that no value token is consumed.
 Typed authors should use canonical `value_type` names (`boolean`, `number`, `string`).
 
 Use `decodeToon` from `@unbrained/pm-cli/sdk/testing` to assert on host output

package/docs/LINKED_TEST_EDITS.md

@@ -77,3 +77,18 @@ gate, and display its recovery message; `exit_code: null` means no subprocess ra
 Context mismatches and a missing required PM assertion also use this result.
 The `TestRunResult.exit_code` type now allows null, and `TestCommandOptions` and
 `TestResult` include the optional editor flags and receipt fields described above.
+
+## Mixed host versions
+
+Tracked by [pm-gh1458](../.agents/pm/issues/pm-gh1458.toon).
+Editor stamps require item format 2. Ordinary records retain format 1, while
+existing unstamped or legacy format-1 records advance only on a real write that
+needs the new fields. Upgrade the CLI, pinned SDK, CI and clone-local merge
+driver together before editing guarded records. Hosts from 2026.10.10 refuse
+with `item_format_version_unsupported`; preserve item/history bytes and upgrade
+instead of lowering the marker or re-anchoring valid history. Inspection of
+legacy 2026.10.12–13 records retains their original history commitments.
+Restoration retains the format requirement even when selecting a pre-edit state.
+The SDK refuses a guarded write when the owning project's declared or resolved
+runtime pins still select a pre-2026.10.10 host. Such hosts predate format
+admission and must be upgraded before they read guarded records.

package/docs/RELEASING.md

@@ -486,6 +486,8 @@ never move a published tag or mint a second automatic version for the same UTC d
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; Sentry requests use the fail-closed bounded `--sentry-request-timeout-ms` contract (default `120000`, maximum `300000`); `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
+- extension grammar acceptance ([pm-gh1466](../.agents/pm/issues/pm-gh1466.toon), [pm-gh1467](../.agents/pm/issues/pm-gh1467.toon)): the existing flag parity gate includes a synthetic extension population, and packed smoke runs the same independent echo oracle on Node and Bun. Immediately before publication, `extension-flag-acceptance.mjs` extracts the exact tarball passed to `npm publish`, resolves its public SDK exports and manifest executable, and checks help, machine contracts, handler options, remaining arguments and refusals. Any failed or missing case stops publication. The retained receipt records executed case identities, runtime, resolved entrypoints, fixture digest and tarball SHA-256. This proves candidate behavior; published-installed acceptance remains a separate claim. Exact-tag recovery preserves both the reviewed runner and its fixture outside the tagged checkout.
+- diagnostic privacy acceptance ([pm-geywoc](../.agents/pm/issues/pm-geywoc.toon)): the same candidate runner requires the independent synthetic diagnostic fixture through the installed public SDK. A disposable loopback collector verifies real serialized error events, streamed spans, and finalized logs, including scope attributes. Quoted keys, Unicode escapes in keys/delimiters/separators, nested serialized JSON, containers and incomplete values must lose their sensitive markers; safe text, numeric/boolean attributes and caller scope must remain intact. Opaque encoded boundaries redact the remaining text, and a long backslash control bounds scanning cost. Missing, failed or duplicate case receipts block acceptance. Recovery preserves the diagnostic fixture with the runner. This local export proof is separate from hosted Sentry ingestion and does not change user consent.
 - sandboxed `pm` coverage
 - a base npm pack dry run, optional Sentry debug-ID injection, a second
   `sentry-injected` packlist budget over the exact publishable bytes, and only

package/docs/SDK.md

@@ -483,6 +483,12 @@ not renderer-specific code, so package authors can reuse
 `resolvePmCommandOutputBudget`, and
 `estimatePmOutputTokens` in custom transports.
 
+Read-output, context-intent, recurrence and diagnostic string compaction retain
+Unicode-safe prefixes. A cutoff through a surrogate pair backs up one UTF-16
+code unit before adding its suffix. Rendering and token receipts use the actual
+retained text; unbounded reads and preserved-string exceptions are unchanged.
+Tracked by [pm-gh1478](../.agents/pm/issues/pm-gh1478.toon).
+
 ```ts
 import {
   definePmCommandOutputBudget,
@@ -946,6 +952,27 @@ 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.
 
+Lifecycle handoff and receipt guidance are tracked by
+[pm-gh1465](../.agents/pm/features/pm-gh1465.toon) and
+[pm-gh1464](../.agents/pm/issues/pm-gh1464.toon). Register a project-specific
+queue with `client.schemaAddStatus("review", { role: ["active"] })`, then call
+`client.release(id, { handoff: "review", message: "Implemented; run linked verification" })`.
+The SDK atomically changes status and clears ownership in one release history
+event, applying project ownership, type-transition, and workflow policies.
+`ReleaseMutationOptions` declares the handoff option; `ReleaseResult.handoff`
+identifies the source and destination states and evidence. `client.list({ status:
+"review" })` selects the verifier queue; context preserves its status without
+counting it as in-progress work. The destination must already exist, be
+non-terminal, and differ from the configured in-progress status. Handoff needs
+a claimed source and evidence message, and cannot be combined with pause.
+
+A successful warning-mode close with missing evidence returns optional
+`follow_up: CloseEvidenceFollowUp`. Its `kind` is `complete_close_evidence` and
+`suggested_command_args` selects an evidence-only update of the same item and
+tracker. Consumers migrating from successful-close `recovery` should read
+`follow_up` instead; a successful close never asks for a retry. Failed close
+commands retain failure recovery. See [close evidence guidance](CLOSE_EVIDENCE_RECOVERY.md).
+
 ### Atomic workspace transactions
 
 Tracked by [pm-4e12](../.agents/pm/features/pm-4e12.toon), with the VCS
@@ -1103,7 +1130,14 @@ bulk sync), `commitItemMutations` wraps the coordinator so callers describe
 the mutations instead of hand-writing a step array. The helper wires the
 crash-consistency contract for you: creates use their resolved stable `id` as
 the idempotency key (exists-by-id inspection) and are compensated by closing
-the item (or deleting it with `createCompensation: "delete"`); updates stamp a
+the item (or deleting it with `createCompensation: "delete"`). A retry refuses
+with `transaction_create_compensated` while a creation's latest closure belongs
+to compensation, even if its close prose was edited. Review its immutable history
+and explicitly reopen it before retrying; the SDK preserves later lifecycle
+decisions instead of silently reopening the item or reporting it committed.
+A later explicit user close or status update takes precedence over the earlier
+compensation close and is preserved when the transaction resumes.
+Updates stamp a
 durable history marker for applied-detection and are compensated by restoring
 the captured pre-mutation version; closes treat an already-terminal target as
 applied and are likewise compensated by version restore; releases restore the
@@ -1241,6 +1275,70 @@ await commitItemMutations({
 });
 ```
 
+For imports, use `planItemMutationDocument` (tracked by
+[pm-gh1456](../.agents/pm/features/pm-gh1456.toon)). It reads the workspace
+schema so declared custom fields route through their option targets, accepts
+JSON Lines and op-less create documents (records shaped like `pm create
+--stdin-json` input, optionally wrapped as `{ ref, item }`), synthesizes
+`row-<n>` aliases for records without `ref`/`id`, derives a stable
+`transaction_id` from the document bytes when none is supplied, and resolves
+`upsertKey` against existing items so matching create records become updates;
+core camelCase option names (such as `acceptanceCriteria`) and declared field
+keys or option targets resolve to the stored metadata key before candidate
+reads and lock-held guards.
+An explicitly supplied blank `upsertKey` is a usage error; omit it to select plain creation.
+Unrelated extension metadata keys retain their exact spelling, including camelCase.
+Item documents also accept known core camelCase option names, including inside
+`{ item }` wrappers. Exact stored metadata keys win when both spellings appear.
+Records that match nothing carry a `unique` guard that `commitItemMutations`
+re-checks under the writer lock and refuses with `upsert_key_conflict` when a
+concurrent writer created the key value after planning; matched records become
+updates carrying a `match` guard checked against the locked target document,
+after acquiring its item lock. It refuses with `upsert_match_changed` when the
+target's key changed in between, including changes made by ordinary item updates.
+Successful update, close and release steps invalidate cached unique-key scans
+inside a mixed batch, so subsequent creates see the current persisted values,
+including changes to earlier creates in that batch.
+Every create also advances cached scans from its returned metadata, including
+unguarded creates and records guarded on a different key, without a new project scan.
+The returned `rows` receipt maps every input record, in order, to its resolved
+`id` and `op`:
+
+```ts
+import {
+  commitItemMutations,
+  planItemMutationDocument,
+} from "@unbrained/pm-cli/sdk";
+
+const plan = await planItemMutationDocument({
+  pmRoot,
+  input: [
+    '{"title":"Imported A","type":"Task","external_id":"ext-1"}',
+    '{"ref":"b","title":"Imported B","type":"Feature","parent":"@row-1","external_id":"ext-2"}',
+  ].join("\n"),
+  upsertKey: "external_id",
+});
+const result = await commitItemMutations({
+  pmRoot,
+  author: "import-agent",
+  transactionId: plan.transaction_id,
+  mutations: plan.mutations,
+});
+console.log(plan.transaction_id_source, plan.rows, result.recovered);
+```
+
+After a successful commit, reuse its transaction id and unchanged resolved
+mutation plan to replay it (`recovered: true`). A formatting-only edit changes
+the derived id; pass the original id explicitly to replay an unchanged plan.
+The planner excludes items created by that transaction from upsert matching,
+retaining those create rows.
+If document edits, external matches, or schema context change the resolved
+plan under that committed id, the coordinator refuses with
+`transaction_plan_mismatch`; use a new transaction id for the changed import.
+Corrupt journal JSON, stored schema version/transaction identity, lifecycle state or metadata instead refuses with
+`transaction_journal_invalid`. Preserve and inspect or restore the journal;
+starting a new id can duplicate work whose durable state cannot be verified.
+
 `buildItemCompletionMutations` creates the ordered evidence/update, close, and
 release plan for inspection. `commitItemCompletion` executes that plan through
 the same durable coordinator, restoring annotations, linked artifacts,
@@ -2225,6 +2323,20 @@ same list/default semantics as core flags:
   `default: "a,b"` or `default: ["a,b", "c"]`) are split into elements. A default
   that would not cleanly coerce under the declared `value_type` (e.g.
   `value_type: "number", default: "abc"`) is rejected at registration.
+- `value_validation` (`"coerce"` | `"strict"`, tracked by
+  [pm-extension-scalar-validation](../.agents/pm/features/pm-extension-scalar-validation.toon))
+  decides what happens to a `number`/`boolean` token that does not coerce.
+  `coerce` is the compatible default: the raw token reaches the handler for its
+  own validation (`--limit abc` arrives as `"abc"`). `strict` refuses the
+  invocation before dispatch with `extension_flag_value_invalid` (exit 2),
+  naming the flag, the command, the expected grammar, and the received token;
+  list entries are checked one by one, including attached values on boolean
+  list switches. CSV boolean lists accept `true,false`; repeatable boolean
+  lists keep each occurrence as one value. Switch presence (`--verbose`,
+  `--no-verbose`), the legacy `bool` optional-value grammar (`--enabled` alone
+  is `true`), declared defaults, and string flags are unaffected. `strict` on a
+  `string` or untyped flag is rejected at registration because there is nothing
+  to validate.
 
 ```ts
 api.registerFlags("report", [
@@ -2235,7 +2347,7 @@ api.registerFlags("report", [
     list: true,
     default: "all",
   },
-  { long: "--limit", value_type: "number", default: 20 },
+  { long: "--limit", value_type: "number", default: 20, value_validation: "strict" },
 ]);
 ```
 

package/docs/TESTING.md

@@ -144,7 +144,7 @@ only after the pushed reviewed head's hosted analyzers are terminal.
 
 ## Published Workspace Compatibility
 
-Tracked by [pm-pae3wo](../.agents/pm/tasks/pm-pae3wo.toon).
+Tracked by [pm-pae3wo](../.agents/pm/tasks/pm-pae3wo.toon) and [pm-gh1458](../.agents/pm/issues/pm-gh1458.toon).
 Run `node scripts/release/workspace-compatibility.mjs --json` after building.
 The policy in `scripts/release/workspace-compatibility-policy.json` requires
 the two immediately preceding stable calendar releases. Each installed release
@@ -172,6 +172,26 @@ entrypoint from their own consumer directory. Raw parsers still preserve future
 markers for integrity inspection; inventory diagnostics are not permission to
 rewrite an unsupported item.
 
+Format 1 remains readable and is still used for ordinary records. Persisting
+linked-test editor stamps requires format 2. The same mutation records that
+marker in history; ordinary subsequent writes, restoration and current-runtime
+merges retain it. Restoring an older state does not lower the reader requirement
+while newer history remains. Existing format-1 editor records written by
+2026.10.12–13 keep their original hashes during inspection and acquire the
+format-2 guard on the next real write. Upgrade every reader, CI runtime and Git
+merge driver before operating on guarded records. Never re-anchor history or
+remove the marker to make an older verifier pass.
+
+The additional published-artifact matrix pins the reported 2026.10.9, 10 and 13
+hosts. It proves original history-prefix preservation, exact nested stamps,
+write refusal when the project still pins 2026.10.9, and CLI/public SDK format
+refusal by 2026.10.10 and 13 without byte changes, ordinary
+current writes, restored states, and native Git merge/reconciliation with the
+upgraded driver. Baseline records still pass the two-prior-release matrix.
+The 2026.10.9 host predates format admission and is not a supported reader of
+guarded records; update project pins and resolved dependencies before writing
+them. That host's mutation bootstrap can then reject the newer project pin.
+
 Run the matrix from the built workspace root. Exact-tag release recovery retains
 the reviewed matrix controls, policy and static fixtures outside the checkout,
 then tests the selected tagged runtime through its manifest and public SDK. A
@@ -630,6 +650,21 @@ pm test <item-id> --run --workspace-context snapshot --override-linked-workspace
   The real filesystem and CLI snapshot suite runs in the required Node 22
   telemetry regression job and native Windows regression job before merge.
 
+  Windows execution is tracked by [pm-bj7rq0](../.agents/pm/issues/pm-bj7rq0.toon).
+  Script and native keeper cohorts run independently on Windows Node 24. Their
+  source/script keeper steps retain the two-worker cap, and each cohort retains
+  the 12-minute deadline. The required
+  `Windows regression (Node 24)` check waits for both cohorts and fails if either
+  fails, is cancelled, or is skipped. This preserves every selected regression
+  while avoiding a shared serial job deadline. See GitHub's
+  [job dependency semantics](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-jobs#defining-prerequisite-jobs).
+
+  The real point-read corpus keeper runs with the lifecycle latency keeper in
+  the existing sequential performance phase after parallel contracts. Its
+  1,500-item corpus, work-observer assertions and 30-second deadline remain
+  unchanged. Standalone script identity is resolved from the test module URL,
+  independently of temporary SDK working directories.
+
   The real-filesystem regression for this contract is tracked by
   [pm-5iwfkj](../.agents/pm/issues/pm-5iwfkj.toon).
 

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -68,7 +68,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `workspace` | workspace | 23 | 23 |
 | `contracts` | quality | 29 | 29 |
 | `claim` | lifecycle | 39 | 39 |
-| `release` | lifecycle | 24 | 24 |
+| `release` | lifecycle | 25 | 25 |
 | `start-task` | lifecycle | 23 | 23 |
 | `pause-task` | lifecycle | 23 | 23 |
 | `close-task` | lifecycle | 24 | 24 |