@unbrained/pm-cli 2026.8.9 → 2026.8.10

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), and the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.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), 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).
 
 ```bash
 pm <command> --help
@@ -358,7 +358,9 @@ pm close-many --rollback close-many-20260604-abc123   # restore the batch
 
 `close-many` skips already-terminal matches by default (pass `--force` to re-close), accepts `--completed-at <timestamp>` to preserve one shared actual-completion time across the batch, reports a per-item plan (`close`/`skip`, plus `active_child_ids` for parents that would be orphaned) under `--dry-run`, and writes a checkpoint by default (`--no-checkpoint` to disable). Checkpoints for both commands live under `.agents/pm/checkpoints/<command>/` and are restored with `--rollback <checkpoint-id>`.
 
-When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`).
+When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`). Unknown-command guidance ranks agent verb synonyms first, bounded edit distance second, and substring matches last; `pm log` therefore points to `history`, `comments`, and `notes`, never a `catalog` command.
+
+Commands addressed to one item retain their canonical positional form and also accept `--id <item-id>` consistently. For example, `pm get --id pm-a1`, `pm comments --id pm-a1 --add "..."`, and `pm test --id pm-a1 --run` are equivalent to their positional forms. Supplying both forms is a usage error. Command-scoped `pm contracts --flags-only`, completion, and help expose the same alias.
 
 ## Create and Update
 
@@ -379,6 +381,7 @@ pm create "Fix login bug" --type Issue --priority high
 `pm create` defaults `--type` to `settings.governance.create_default_type` (falling back to `Task`).
 Set it with `pm config project set governance-create-default-type <Type>` (must resolve to a known item type).
 Pass `--create-mode strict` to require an explicit `--type` flag for governance-controlled flows.
+Type-aware help reports requirements for the selected mode and lists stricter requirements separately. A strict required repeatable collection can be deliberately empty: for example, `--clear-deps` satisfies a required dependency consideration while writing no relationship edge and recording `explicit_unset=dependencies` in history. Required runtime-schema fields are named with their metadata key and expected input format in structured recovery.
 `pm update --status` can be constrained per item type via `schema.type_workflows` plus
 `pm config project set governance-workflow-enforcement <off|warn|strict>` (see CONFIGURATION.md → Per-Type Workflows).
 Priority accepts either `0..4` or the equivalent names `critical`, `high`, `medium`, `low`, and `minimal`.
@@ -450,7 +453,7 @@ pm update pm-abc1 --remove-tags stale            # drops "stale", keeps the rest
 pm create "New backend task" --add-tags backend,p1
 ```
 
-Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` REPLACES the whole value, while `--add-ac <text>` appends one criterion (repeatable; deduped on exact text) and `--remove-ac <text>` removes one criterion by exact text match (repeatable; a non-matching selector adds a `remove_ac_unmatched:<text>` warning instead of silently no-oping). Criteria are stored with semicolon-space separators, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
+Acceptance criteria get the same additive treatment on `update`/`update-many`: `--acceptance-criteria`/`--ac` explicitly REPLACES the whole value and returns an `acceptance_criteria_replaced:<before-count>:<after-count>` warning when it changes existing criteria. `--add-ac <text>` appends one criterion (repeatable; deduped on exact text), while `--remove-ac <text>` removes one criterion by exact text match. Every requested removal must match: otherwise the mutation fails atomically with `acceptance_criteria_remove_unmatched` and reports the unmatched selectors, without applying valid removals or additions. Whole-value replacement cannot be combined with additive flags in one mutation. Criteria are stored with semicolon-space separators, so one criterion cannot contain a semicolon. Disjoint `--add-ac` edits from concurrent agents/branches merge cleanly instead of clobbering each other.
 
 ```bash
 pm update pm-abc1 --add-ac "error path covered by a regression test"
@@ -489,7 +492,7 @@ pm update <id> \
 pm update <id> --expected "Retry succeeds after backoff" --actual "Retry threw on first attempt"
 ```
 
-Repeat `--ac`/`--acceptance-criteria` to build multi-part criteria; values are stored in order joined by `; `. Dependency inputs accept either a bare existing item id or the explicit `id=<id>,kind=<kind>` form, and malformed shorthand such as `related:pm-abcd` fails before it can create a dangling graph edge.
+Repeat `--ac`/`--acceptance-criteria` to build multi-part criteria; values are stored in order joined by `; `. Dependency inputs accept either a bare existing item id or the explicit `id=<id>,kind=<kind>` form, and malformed shorthand such as `related:pm-abcd` fails before it can create a dangling graph edge. New local dependency targets must already exist. Cross-workspace targets must declare `source_kind=external` (canonicalized to `global`); deliberately staged local edges require `--allow-unresolved-deps` and return one structured `dependency_target_unresolved:<id>` warning per missing target. The same validation runs during `update-many --dry-run`, so preview and apply cannot disagree.
 
 Mutation commands (`create`/`update`/`close`/`append`/...) default to an
 agent-efficient `id`/`status`/`changed_field_count` envelope. Use
@@ -747,7 +750,7 @@ pm test <id> --run --only-last
 pm test-all --status in_progress --progress
 ```
 
-Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` for repo-local test suites; normal package-manager scripts such as `pnpm test` and `npm run test` are accepted because linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH`. Direct runner binaries such as `vitest` or `node --test` still need the wrapper or explicit inline sandbox env. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
+Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` for repo-local test suites; normal package-manager scripts such as `pnpm test` and `npm run test` are accepted because linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH`. Direct runner binaries such as `vitest` or `node --test` still need the wrapper or explicit inline sandbox env. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. Linked tests retain append order; consequently `--only-last` always selects the most recently added stored test. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
 
 Strict linked-test guards:
 

package/docs/MERGE_SAFETY.md

@@ -65,11 +65,13 @@ When both sides change the same item scalar differently, the driver writes the s
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
 
-For item conflicts, the driver also writes a clone-local receipt below the Git
-directory. It contains retained and discarded values so recovery does not
-depend on a reflog. Raw values never enter public tracker history:
-reconciliation records field names and value hashes, while the explicit local
-report is the only command that shows recoverable values:
+For item conflicts, the driver writes a clone-local receipt below the Git
+directory and a durable privacy-safe sidecar below `merge-receipts/` in the
+tracker. The local receipt contains retained and discarded values so recovery
+does not depend on a reflog. The tracked sidecar contains only field names and
+value hashes, so fresh clones and CI can still fail closed on an unreviewed
+decision without publishing either value. When both copies exist the SDK
+deduplicates them and prefers the locally recoverable copy:
 
 ```bash
 pm merge report

package/docs/README.md

@@ -46,17 +46,14 @@ pm guide release --json
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
-- [SDK Context Truth Contracts](SDK_CONTEXT_TRUTH_CONTRACTS.md) - typed tracker-root diagnostics and explicit merge-driver enforcement policy.
+- [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
 - [Self-Describing Context Contracts](SELF_DESCRIBING_CONTEXT_CONTRACTS.md) - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
-- [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md) - durable mutation events, bounded duplicate governance, and scale-safe package primitives.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [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.
-- [SDK Context Integrity Primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) - batch duplicate discovery, structured errors, Plan evidence/lifecycle, sparse settings, tombstones, linked-test output, relocation diagnostics, and scoped output services.
-- [SDK Context Integrity](SDK_CONTEXT_INTEGRITY.md) - truthful `get` projections, bounded annotation mutations, shared author coordinates, health provider boundaries, and changeset-aware replication gates.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
@@ -80,7 +77,7 @@ pm guide release --json
 | `quickstart`              | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md)                                       |
 | `commands`                | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md)                                 |
 | `workflows`               | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md)                                                |
-| `sdk`                     | [SDK](SDK.md), [Architecture](ARCHITECTURE.md)                                                      |
+| `sdk`                     | [SDK](SDK.md), [SDK context contracts](SDK_CONTEXT.md), [Architecture](ARCHITECTURE.md)             |
 | `extensions`, `packages`  | [Packages and Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
 | `skills`                  | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*`                                               |
 | `harnesses`               | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md`                        |

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -60,8 +60,8 @@ also fixes the expected unique-fact shape:
 
 | Tracker tier | Group spend / budget | Seen items | Suppressed repeats | Delivered bytes |
 | ------------ | -------------------- | ---------- | ------------------ | --------------- |
-| 2 items      | 3,663 / 20,000       | 2          | 3                  | 14,646          |
-| 2,243 items  | 9,999 / 20,000       | 106        | 7                  | 39,985          |
+| 2 items      | 3,820 / 20,000       | 2          | 3                  | 15,274          |
+| 2,243 items  | 10,156 / 20,000      | 106        | 7                  | 40,614          |
 
 These are deterministic synthetic-corpus measurements from
 `scripts/release/context-intent-calibration.json`; they contain no hosted

package/docs/SDK.md

@@ -35,6 +35,14 @@ ownership are tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
 [pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
 [pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
 
+Shared item addressing, lossless recovery, explicit-empty create policy,
+semantic command discovery, and append-stable linked tests are tracked by
+[pm-mkinft](../.agents/pm/issues/pm-mkinft.toon),
+[pm-p316vn](../.agents/pm/issues/pm-p316vn.toon),
+[pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon),
+[pm-g543](../.agents/pm/issues/pm-g543.toon), and
+[pm-x2vx](../.agents/pm/issues/pm-x2vx.toon).
+
 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.
 
 ## Install
@@ -309,6 +317,7 @@ Command/action contract exports:
 - Execution and diagnostics engines: `runTest`, `runLinkedTests`, `runTestAll`, `runStartBackgroundRun`, `runTestRunsList`, `runTestRunsStatus`, `runTestRunsLogs`, `runTestRunsStop`, `runTestRunsResume`, `runTestRunsWorker`, `runEval`, `runTelemetry`, and `runStats`. Their CLI modules are compatibility re-exports of SDK-owned implementations.
 - 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` and `resolveMissingOptionPlaceholder` preserve attempted argv while deriving enum, boolean, and scalar recovery arity from flag contracts; `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.
 - 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`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, `packageMigrate`, and `upgrade`; one-shot `extensionMigrate` and `packageMigrate` helpers mirror those lifecycle actions.
@@ -1272,11 +1281,21 @@ const result = await commitItemMutations({
 `commitWorkspaceTransaction` remains the escape hatch for arbitrary domains
 (relationship events, foreign stores, mixed-step plans); `commitItemMutations`
 covers the item-mutation 90% case with correct-by-construction wiring.
-Update mutation options use the same acceptance-criteria representation as the
-CLI: criteria are stored in one string with semicolons as boundaries. Therefore
-each `addAc`/`removeAc` entry must be semicolon-free; unmatched removals are
-reported as `remove_ac_unmatched:<text>` warnings rather than disappearing as
-silent no-ops.
+Update mutation options use the same lossless acceptance-criteria contract as
+the CLI: criteria are stored in one string with semicolons as boundaries, so
+each `addAc`/`removeAc` entry must be semicolon-free. Every removal must match or
+the complete mutation rejects with `acceptance_criteria_remove_unmatched` and
+structured `unmatched` recovery data. Whole-value `acceptanceCriteria`
+replacement is mutually exclusive with additive edits and returns an
+`acceptance_criteria_replaced:<before-count>:<after-count>` warning when it
+changes existing criteria.
+
+Create and update mutation options also resolve every newly supplied local
+dependency target before persistence. Use `source_kind: "external"` for a
+cross-workspace endpoint. A staged local import must opt in with
+`allowUnresolvedDeps: true`; successful results then retain one
+`dependency_target_unresolved:<id>` warning per missing target. Bulk dry-runs
+perform the identical validation before producing a plan.
 
 `parseItemMutationBatch` is the strict legacy JSON boundary for that primitive. It
 accepts either a non-empty mutation array or `{ "mutations": [...] }`, derives
@@ -3258,9 +3277,15 @@ For SDK and automation consumers, the key runtime change is the optional `recove
 - `suggested_retry`
 
 Treat `recovery.suggested_retry` as the first-choice deterministic replay
-command when present. It is emitted only from structured recovery metadata or
-flags declared on the invoked command; prose that merely mentions another flag
-is not interpreted as a missing input.
+command when present. Generic missing-option retries preserve every original
+argv token, insert only absent real flags before the first `--` argument
+terminator while leaving that terminator in place, and derive placeholders from
+the declared flag domain (`<off|warn|strict>` for enum values and no placeholder
+for booleans). It is emitted only from structured recovery metadata or flags
+declared on the invoked command; prose that merely mentions another flag is not
+interpreted as a missing input. Strict close validation reports missing
+resolution fields first and suggests a targeted `pm update` before retrying the
+original close invocation.
 
 ## Authoring Pattern
 

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -95,14 +95,15 @@ host declarations retain precedence over this inference.
 `diagnoseAgentIdentity()` is the additive diagnostic companion to
 `detectAgentIdentity()`. It returns the same privacy-safe identity plus a
 `provenance_outcomes` row for every built-in dimension. Each row is
-`resolved`, `unavailable`, or `failed`, carries rule version `v1`, and may name
+`resolved`, `unavailable`, `not_configured`, or `failed`, carries rule version `v1`, and may name
 the bounded built-in resolver. It never contains environment values, session
 paths, prompts, or file contents.
 
 New mutation history records failed resolver outcomes under
 `context.agent_provenance_outcomes`; ordinary unavailable dimensions retain
 the compact legacy-compatible null projection. A resolver is only counted as
-attempted when its required input exists. Consequently `pm health` can report
+attempted when its required input belongs to the detected harness; a foreign
+host's shared `AI_AGENT` value is not Codex input. Consequently `pm health` can report
 `provenance_resolver_zero_success:<harness>:<dimension>:<resolver>:<attempts>`
 without confusing an unavailable harness signal with a failed resolver. The
 warning is advisory and the storage check includes the bounded attempt and

package/docs/SDK_CONTEXT.md

@@ -0,0 +1,97 @@
+# SDK context platform
+
+Tracker: [pm-9hv1o7](../.agents/pm/issues/pm-9hv1o7.toon).
+
+`pm` treats project management as context management. This task-oriented entry
+point routes SDK hosts, package authors, CLI integrators, and agents to the
+smallest authoritative context primitive.
+
+## Choose the smallest authoritative read
+
+- Use `PmClient.context()` for ranked working context and bounded workspace memory.
+- Use `PmClient.listAllItemMetadataLight()` or
+  `listAllItemMetadataLight(pmRoot)` for whole-project scalar metadata without
+  bodies or heavy annotation/evidence collections.
+- Use `PmClient.get(id, { depth: "deep" })` when one item needs its complete
+  collections. Shallower reads carry an omission receipt naming every withheld
+  group and the exact `--fields` restoration.
+- Use mutation events for changes since a cursor instead of repeatedly loading
+  a full workspace.
+
+The root package, `sdk/runtime`, and `PmClient` expose the lightweight reader.
+It distinguishes an empty tracker from a missing or invalid root and preserves
+custom item-type folders from workspace settings.
+
+## Rank and pack context
+
+Context ranking combines recency, activity, graph proximity, priority, risk,
+knowledge density, structural fit, and caller affinity. Derived signal snapshots
+are rebuildable; item documents and history remain authoritative. Invalid,
+stale, or unwritable snapshots return a stable warning, its meaning, an
+executable recovery command, and the expected effect. Re-running `pm context`
+confirms a successful rebuild as fresh.
+
+See [Context relevance and packing](CONTEXT_RELEVANCE.md) for signal and token
+budgets, and [context coordination](SDK_CONTEXT_COORDINATION.md) for cursored
+events and duplicate governance.
+
+## Preserve truth at boundaries
+
+Bounded reads disclose omissions. Bounded annotation mutations return the
+changed entry instead of replaying complete history. Unknown-author findings
+route directly to append-only attribution. Diagnostics remain read-only unless
+a mutation is explicitly selected.
+
+See [context integrity](SDK_CONTEXT_INTEGRITY.md) for output selectors,
+annotation receipts, attribution coordinates, provider boundaries, and
+replication enforcement; see [truth contracts](SDK_CONTEXT_TRUTH_CONTRACTS.md)
+for tracker-root and merge-driver distinctions.
+
+## Build package workflows
+
+Use the root SDK for application workflows and `sdk/runtime` for dependency-light
+host primitives. Runtime contracts are authoritative for active flags and
+package-contributed commands:
+
+```bash
+pm <command> --help --json
+pm contracts --command <command> --flags-only --json
+pm contracts --runtime-only --json
+```
+
+Use `findSimilarItems` for one proposal, `findDuplicateClusters` for a bounded
+whole-tracker sweep, and `prepareSimilarityText` with
+`scorePreparedItemSimilarity` for custom pipelines. All paths share one
+canonical Jaccard implementation and one canonical status-token normalizer.
+
+See [context integrity primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) for
+duplicate batches, structured errors, Plan evidence, tombstones, linked-test
+output, and extension output ownership.
+
+## Validate and recover
+
+Fast health projections use light metadata. Validation materializes collections
+needed by evidence and relationship checks, but loads bodies only for strict
+history-drift verification. Unknown-author remediation is shared:
+
+```bash
+pm health --verbose-author-events --json
+pm history-author-acknowledge --all-actionable \
+  --attributed-author "<principal>" \
+  --reviewer "<reviewer>" \
+  --reason "<evidence>"
+```
+
+Run repository gates after public SDK changes:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm quality:surface-replication
+pnpm sdk:surface:check
+node scripts/run-tests.mjs coverage
+```
+
+The replication gate reports an AST-derived denominator of repeated named rule
+bodies and enforces a non-decreasing detector floor, so deleting declarations
+cannot make recurring implementation rules disappear from governance reports.

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -18,6 +18,12 @@ pm get pm-a1b2 --output-include item,claim_state
 
 An unknown selector is a usage refusal that lists the valid vocabulary. Selecting the complete `item` object together with an item field is also refused because the two selectors express conflicting projection depths. Every successful projection carries an `omission_receipt` with the exact selectors needed to restore withheld item fields or sections.
 
+Automatic receipts cover every heavy item collection (`comments`, `notes`,
+`learnings`, `files`, `tests`, `docs`, `reminders`, and `events`) plus `body`,
+`children`, `claim_state`, `linked`, and `schedule`. Empty included collections
+are distinguishable from omitted collections because inclusion is derived from
+property presence, not collection length.
+
 Standard and brief item reads expose the stable `collection_counts` selector;
 full reads retain those counts and normalize every supported collection key to
 an array. `--output-include item.collection_counts` therefore uses the same
@@ -49,7 +55,7 @@ pm history-author-acknowledge \
   --reason "Verified workspace provenance"
 ```
 
-The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar.
+The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar. Health and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
 
 ## Health provider boundary
 
@@ -57,11 +63,18 @@ The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAu
 
 Storage integrity is evaluated independently of that provider boundary. Lossless merge receipts remain visible as provenance, while only receipts containing discarded scalar values produce `merge_decisions_unreviewed` guidance; neither classification enables vector refresh or remote provider I/O.
 
+Brief and summary check-only health projections use the scalar-only metadata
+reader. Validation uses collection-bearing metadata for evidence and
+relationship checks and materializes bodies only when strict history-drift
+verification is requested.
+
 The storage check also reads at most 10,000 local immutable events for bounded
 agent-provenance resolver outcomes. This scan performs no network or provider
 I/O, tolerates malformed streams already owned by integrity diagnostics, and
 reports an advisory warning only when a resolver was actually attempted but
-never succeeded.
+never succeeded. The same bounded pass classifies bare boolean and single-digit
+values across every recorded provenance dimension, publishes only aggregate
+harness/dimension/kind counts, and never echoes the historical value.
 
 ## Replication and refusal gate
 
@@ -70,7 +83,9 @@ never succeeded.
 - active set recurrence density;
 - the largest source member’s utilization of the mandatory file-size cap;
 - every remaining CLI-owned `PmCliError`, grouped by an explicit adapter-level disposition;
-- applied waivers, including their PM owner and expiry.
+- applied waivers, including their PM owner and expiry;
+- an AST-derived denominator of identical named rule bodies, declared coverage,
+  and a non-decreasing detected-cluster floor.
 
 Query waivers directly with:
 

package/docs/agent-task-token-baseline.json

@@ -14,12 +14,12 @@
     },
     {
       "id": "returning-agent",
-      "max_estimated_tokens": 383
+      "max_estimated_tokens": 597
     },
     {
       "id": "failing-command",
       "max_estimated_tokens": 197
     }
   ],
-  "composite_max_estimated_tokens": 2437
+  "composite_max_estimated_tokens": 2651
 }

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.9"
+    "version": "2026.8.10"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.9",
+      "version": "2026.8.10",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/absence-tolerance-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
     "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -133,6 +133,7 @@
     "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
     "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
     "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
+    "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
     "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
     "quality:hosted-analysis": "node scripts/release/hosted-analysis-gate.mjs",
@@ -160,8 +161,8 @@
     "version:next": "node scripts/release-version.mjs next",
     "version:sync": "node scripts/sync-versions.mjs apply",
     "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
-    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
-    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
+    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --exclude-tag changelog-exclude --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
+    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --exclude-tag changelog-exclude --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
     "verify:preflight": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.8.9",
+  "version": "2026.8.10",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",