@unbrained/pm-cli 2026.10.15 → 2026.10.18

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

@@ -209,6 +209,32 @@ Each aggregate row carries an explicit `group_label`: a blank/null group value (
 pm list --all --sort updated --order desc
 ```
 
+Brief list rows include an explicitly selected sort field (including normalized
+aliases such as `updated_at`) and declare it in `projection.fields`. Explicit
+`--fields`, compact and full projections retain their requested fields.
+This rule is shared by SDK list queries.
+
+Lifecycle filters such as `--all` and `--status all` retain the canonical `list`
+command's brief default; they select rows without expanding item fields. Use
+`--full`, `--compact`, `--brief`, `--fields` or `--include-body` to choose more
+evidence explicitly. Raw SDK list calls keep their full default, and explicit
+`--all --full --strict-read` remains a complete corpus read.
+The implementation records
+[pm-gh1481](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1481.toon)
+and [pm-gh1489](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1489.toon)
+are repository-only tracker files, excluded from the npm package.
+
+New dependency writes record `created_at`. Supplied values must be calendar-valid
+RFC 3339 date-times. SDK dependency reads expose this field as optional because
+legacy rows without a timestamp remain readable: they sort before timestamped
+rows, with deterministic id/kind/source
+tie-breakers and no invented provenance. An invalid supplied timestamp produces
+`item_document_invalid` with the item path and dependency field.
+`pm validate --check-storage-integrity` and `pm health --check-only --full` expose
+that malformed item. The implementation record
+[pm-gh1482](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1482.toon)
+is a repository-only tracker file, excluded from the npm package.
+
 ### Incremental "what changed since" filters
 
 Every `list*` command accepts `--updated-after`/`--updated-before`/`--created-after`/`--created-before`. `pm search` now supports the SAME filter surface as `pm list` (full parity): `--status`, `--type`, `--tag`, `--priority`, `--deadline-before`/`--deadline-after`, `--updated-after`/`--updated-before`, `--created-after`/`--created-before`, `--assignee`, `--sprint`, `--release`, and `--parent`, all with identical semantics. These keep a long-running agent's context focused on the slice it cares about instead of re-scanning the whole tracker:
@@ -620,14 +646,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 \
@@ -644,13 +675,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/CONFIGURATION.md

@@ -148,6 +148,18 @@ For command-level tracker targeting, prefer `--pm-path <tracker-root>`. The old
 itself, not the repository workspace. During `pm init`, explicit tracker paths
 that look like workspace roots are rejected unless `--force` is provided.
 
+Implicit discovery checks the current directory and its ancestors up to the
+nearest `.git` directory or file, including worktrees and submodules. An
+uninitialized repository selects its own `.agents/pm` and returns initialization
+recovery instead of reading or changing an enclosing repository's tracker.
+Ordinary subdirectories still share their repository's tracker, including
+root-layout trackers. To deliberately share a tracker across repository
+boundaries, pass `--pm-path <tracker-root>` or set `PM_PATH` explicitly.
+This shared SDK discovery policy also applies to CLI and MCP commands.
+Directory aliases follow physical ancestry, including missing descendants of
+an existing alias. Unexpected directory or `.git` lookup errors stop discovery
+instead of falling through to an enclosing tracker.
+
 Tests should set both `PM_PATH` and `PM_GLOBAL_PATH` to temporary directories. The wrapper `node scripts/run-tests.mjs ...` does that automatically.
 
 ### Telemetry environment variables
@@ -212,7 +224,16 @@ Interaction rules:
 - `pm health --check-telemetry --json` surfaces flush and OTLP export diagnostics (`pending_otel_spans`, `last_otel_attempt_at`, `last_otel_success_at`, `last_otel_failure_at`, `last_otel_failure_error`) and the active `env_overrides` (including `telemetry_inline_flush` and `telemetry_source_context`) so agents can self-diagnose a stalled endpoint.
 - An explicit `PM_AUTHOR` override adds a privacy-preserving agent-identity dimension to `command_start`/`command_finish` events so overridden invocations can be segmented in dashboards without leaking the raw author string. At `redacted`/`max` capture the events carry `author_context_hash` — the same installation-id-keyed one-way SHA-256 used for `pm_root_hash`/`cwd_hash`, so the same author hashes consistently within an installation but differently across installations. At `minimal` capture only a boolean `has_author_context` is emitted. The raw `PM_AUTHOR` value is never exported.
 
-Test environments inferred from `VITEST`, `VITEST_WORKER_ID`, or `NODE_ENV=test` suppress telemetry before identity creation. A valid explicit `PM_TELEMETRY_SOURCE_CONTEXT` or `PM_TELEMETRY_SEND_TEST_EVENTS=1` permits intentional test delivery. Point such tests at a local collector. Neither setting overrides a hard opt-out. `pm telemetry status` exposes effective `enabled`, persisted `configured_enabled`, and `env_overrides` so an empty queue is distinguishable from disabled delivery.
+Test environments inferred from `VITEST`, `VITEST_WORKER_ID`, `NODE_TEST_CONTEXT`
+(native `node --test` children), or `NODE_ENV=test` suppress telemetry and Sentry
+before identity creation. A valid explicit `PM_TELEMETRY_SOURCE_CONTEXT` or
+`PM_TELEMETRY_SEND_TEST_EVENTS=1` permits intentional test delivery. Point such
+tests at a local collector. Inferred tests use inline telemetry flushing even
+after an opt in, so CLI delivery settles before process exit and disposable-root
+cleanup. SDK telemetry completion also awaits inline delivery before returning.
+Neither setting overrides a hard opt-out. `pm telemetry status` exposes effective `enabled`, persisted
+`configured_enabled`, and `env_overrides` so an empty queue is distinguishable
+from disabled delivery.
 
 SDK consumers that previously used `TelemetryStatusSummary.enabled` to display the saved preference should read `configured_enabled` instead. Use `enabled` to determine whether this process permits delivery.
 

package/docs/DEVELOPMENT_DEPENDENCY_SECURITY.md

@@ -20,6 +20,13 @@ nightly quality and release paths enforce it. The registry-owned local
 preflight also requires the static gate and permits no skip. Trivy separately
 includes development dependencies in its required repository scan.
 
+Composite action refs and their executed tool versions need separate review.
+[pm-38w3ii](../.agents/pm/chores/pm-38w3ii.toon) pins TruffleHog's action
+commit and explicitly selects scanner version `3.98.0`; the action otherwise
+defaults to the `latest` image. The workflow contract checks both values on
+every TruffleHog step. Recheck the action's executable selectors when renewing
+its commit pin.
+
 ## Indexed source-map offsets
 
 [pm-dba47](../.agents/pm/issues/pm-dba47.toon) tracks Dependabot alert 47 and
@@ -109,9 +116,21 @@ program matches the reviewed [shim templates](../config/codspeed-shims/), with
 targets and module paths derived from the audited installed dependency. Arbitrary
 names, nested payloads, links, altered programs and forged target markers fail;
 these shims are outside the twelve package-owned hashes but are independently
-validated. The shell template records pnpm 11.10.0's installed output; the CMD
-and PowerShell templates come from `@zkochan/cmd-shim` 9.0.7. Template changes
-require renewed real installation evidence on both POSIX and native Windows.
+validated. [pm-rnpmtp](../.agents/pm/chores/pm-rnpmtp.toon) renews the installer
+to pnpm 11.28.5 and its bundled `bins/cmd-shim` generator. Separate complete shell
+templates describe POSIX and Windows installations; only the host's template is
+accepted. Windows shells pass Windows `NODE_PATH` values to native Node, and
+Cygwin targets use Windows paths. CMD and PowerShell programs retain their
+complete comparisons. Template changes require renewed real installation and
+dependency-resolution evidence on POSIX, Git Bash and Cygwin, plus CMD and
+PowerShell. The Windows script cohort downloads the archived Cygwin setup 2.937
+installer and verifies its pinned SHA-512 before execution. To renew it, select
+an eligible version from the official [setup archive](https://cygwin.com/setup/),
+verify the executable against the archive's `sha512.sum`, and update the
+versioned URL, pinned digest and workflow contract together. Preserve setup's
+default package-signature verification and repeat native launcher acceptance.
+Literal percent paths are exercised in disposable launcher fixtures;
+the audited CodSpeed installation still refuses shell interpolation paths.
 The CMD suffix follows the installed `PATHEXT` spelling, including `.CMD`;
 format lookup folds its case while validating the complete program. All three
 shell launchers are required, together with the CMD and PowerShell sets on

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

@@ -1,5 +1,15 @@
 # Output Projection and Omission Contracts
 
+Passing extension health defaults are tracked by
+[pm-gh1486](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1486.toon),
+a repository-only tracker file excluded from the npm package. Standard `pm health` output
+reports healthy extension counts and `restore_with: "pm health --full"` rather
+than the command registry. Its `standard` projection declares the omitted full
+check details. Warning and failure details remain available by default.
+`--full` restores structured evidence; `--brief` never expands an individual
+check's serialized detail beyond the standard projection. Summary and check-only
+verdict semantics remain unchanged. SDK `runHealth` and MCP use the same engine.
+
 Tracker references: [pm-p258tx](../.agents/pm/features/pm-p258tx.toon),
 [pm-cyrfjq](../.agents/pm/issues/pm-cyrfjq.toon), and
 [pm-qhnq6t](../.agents/pm/issues/pm-qhnq6t.toon). The universal row and

package/docs/RELEASING.md

@@ -304,7 +304,14 @@ The release workflow publishes this staged tarball with provenance; CI and
 packed smoke tests use the same staging command. Application distribution and
 bundled runtime have separate committed size and file-count limits, so runtime
 payload cannot hide application growth. The ledger ships with the tarball for
-installed-version verification. npm 12 ignores published shrinkwraps; shipping
+installed-version verification. [pm-iceees](../.agents/pm/issues/pm-iceees.toon)
+keeps selected optional-peer subtrees complete: npm deliberately skips peer edges
+when gathering bundled files, so staged runtime manifests record the exact tested
+peer bindings as ordinary or optional dependency entries. Package code, source
+and installed manifests, peer declarations, and the root public dependency
+inventory remain intact. A real archive regression resolves the peer's descendant
+from an extracted package and the installed-runtime verifier still refuses any
+missing locked package. npm 12 ignores published shrinkwraps; shipping
 a shrinkwrap alone therefore cannot enforce this contract. SDK consumers
 supply the bounded optional Node types peer themselves.
 

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

@@ -1,6 +1,8 @@
 # SDK context coordination primitives
 
-Trackers: [pm-e200](../.agents/pm/features/pm-e200.toon), [pm-ez1dfg](../.agents/pm/tasks/pm-ez1dfg.toon), [pm-4ri6](../.agents/pm/features/pm-4ri6.toon), and [pm-hcrmye](../.agents/pm/issues/pm-hcrmye.toon).
+Trackers: [pm-e200](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-e200.toon), [pm-ez1dfg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ez1dfg.toon), [pm-4ri6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-4ri6.toon), [pm-hcrmye](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hcrmye.toon), [pm-gh1485](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1485.toon), and [pm-xj80p9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xj80p9.toon).
+
+Tracker records live in the repository and are excluded from the npm package.
 
 `pm` treats project management as context management. These primitives let an
 agent learn what changed, avoid creating redundant work, and keep that work
@@ -38,10 +40,61 @@ idempotently or deduplicate replays. `--cursor-mode row` preserves the previous
 shape with one `cursor` per event and no trailer for consumers that checkpoint
 every row. Already issued version-1 cursors remain accepted by `--since`.
 
-Node runtimes use the rebuildable SQLite event projection. Runtimes such as Bun
-that do not expose `node:sqlite` transparently scan the authoritative history
+Version-1 cursor ordering uses recorded timestamps, stream ids, and offsets.
+A fact committed later with an older timestamp falls before an advanced cursor.
+Clock-independent ordering and late-commit recovery remain tracked by
+[pm-10l1vm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-10l1vm.toon). Hosts needing complete concurrent
+observation can retain a fixed lower boundary and deduplicate snapshots by
+`item_id` and `version` while work is being committed.
+
+Runtimes exposing `node:sqlite` use the rebuildable SQLite event projection.
+Runtimes without it transparently scan the authoritative history
 streams with the same ordering, filters, pagination, and cursor contract; pages
 identify that path with `source: "authoritative_history"`.
+Writers without SQLite use the same pending and committed invalidation protocol,
+so a later Node writer cannot certify a cache that omitted their facts.
+Incremental writes also verify the previous size receipt before advancing it,
+so merged history cannot be hidden by a later append. Upgraded runtimes rebuild
+legacy projections that could contain omitted facts with apparently current
+receipts; authoritative history does not require a format migration.
+
+Index readers take a synchronous SQLite read transaction containing both event
+rows and their stream-size receipts, then close the database before checking
+authoritative files. They acquire neither history-index writer lock. File
+identity and write timestamps, authoritative stream sizes, and pending or
+committed invalidations must still match before a snapshot is returned. A
+concurrent change refuses the optional snapshot; it cannot certify older rows
+using a newer size receipt.
+
+Incremental projection writes also use a zero SQLite busy timeout. Native
+reader or writer contention falls back to the authoritative append and
+invalidation protocol instead of spending a separate SQLite wait budget.
+An unexpired, token-owned append lease marks ordinary incremental work as
+active until its commit or invalidation completes. Native contention retains
+the cache file and a committed contention marker; a zero-wait native probe
+distinguishes an ongoing contender from settled damage before requesting repair.
+
+Authoritative writers fail fast when an active owner holds the projection writer
+lock, including when a full repair owns it. They publish an invalidation instead.
+Stale-owner recovery follows the built-in lock policy. A repair
+refuses publication if those markers changed during its scan. Full projection
+construction yields between batches, and marker cleanup occurs outside the
+short invalidation publication lock.
+After a refused full publication or failed repair, a best effort per-tracker runtime receipt
+defers automatic repair for five seconds. Busy periods therefore do not restart
+a complete SQLite build on every read. Pages and recency reads continue using
+authoritative history; after the cooldown, a later read can repair during a
+quiet interval. This backoff bounds repair frequency, not index availability
+during continuous writes.
+
+Transient generation changes and SQLite contention use authoritative fallback
+directly. Missing, incompatible, or damaged projections receive one optional
+repair attempt without waiting for either projection lock. Repair failure or
+invalidation after rebuilding
+falls back to authoritative JSONL with the same filters and cursor format.
+Pages may change `source` between calls. A fallback still reports malformed or
+inaccessible authoritative history as an error. A successful repair may scan
+the workspace; this protocol bounds lock waiting, not total execution time.
 
 `--full` also includes the complete authoritative history entry.
 `--type`, `--author`, and `--item` accept repeatable or comma-separated values.
@@ -109,10 +162,7 @@ Package authors can query the same scorer used by create/copy and the bundled
 governance audit:
 
 ```ts
-import {
-  findSimilarItems,
-  scoreItemSimilarity,
-} from "@unbrained/pm-cli/sdk";
+import { findSimilarItems, scoreItemSimilarity } from "@unbrained/pm-cli/sdk";
 
 const score = scoreItemSimilarity("Fix OAuth refresh", "Fix oauth refresh");
 const matches = await findSimilarItems(
@@ -155,6 +205,20 @@ accepted aliases for existing automation.
 
 ## Scale contract
 
+The mixed-reader acceptance used 100 fixed-boundary snapshot observers,
+five SDK writer lanes, and five CLI writer lanes, with five updates per lane.
+Both separate traced and untraced cohorts passed 5,000 unique observations,
+duplicate-free pages, strict history integrity, and a 2,000 ms first-observation
+ceiling. These are bounded host measurements recorded in
+[pm-gh1485](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1485.toon).
+
+The native regression suspends filesystem validation and requires an
+authoritative writer to finish before that reader resumes. Run it with:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/core/history/event-index-snapshots.spec.ts
+```
+
 Event catch-up reads from a persistent ordered projection and follows only new
 rows. Similarity governance is zero-cost when off and index-bounded when
 enabled on an indexed workspace. Production bundles are syntax-, whitespace-,