@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/docs/ASSURANCE.md

@@ -0,0 +1,132 @@
+# Project Assurance Primitives
+
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon)
+
+## Agent Quick Context
+
+Assurance turns project policy into three reusable SDK-owned declarations:
+
+1. A **measurement** selects authoritative project data and produces a number or labelled set plus population, contributor, and compute-cost receipts.
+2. An **assertion** applies exactly one explicit bound, scope, lifetime, and enforcement level to a measurement. Required negative controls prove that the bound can both pass and fail.
+3. A **gate** evaluates named assertions at declared lifecycle triggers and returns one structured verdict shared by CLI, SDK, MCP, and CI callers.
+
+Declarations live in `.agents/pm/assurance.json`. Every registry mutation and non-dry gate verdict is appended through the verified workspace history stream; never edit either file directly.
+
+## Why Assurance Exists
+
+Project management is context management. A useful quality gate therefore needs more than a shell exit code: it must preserve what was measured, which population was judged, why a bound exists, who owns it, what changed the result, how expensive the evaluation was, and which immutable tree received the verdict.
+
+The assurance SDK keeps those semantics independent from presentation. Commander and MCP only normalize inputs. Package authors and CI hosts can use the same public functions without reconstructing policy in scripts.
+
+## Declaration Vocabulary
+
+Measurements support these built-in sources:
+
+| Source | Purpose |
+| --- | --- |
+| `items` | Count items matching status, type, tags, or an exact metadata field. |
+| `dependency_kind` | Count typed relationship edges such as `blocked_by` or `verifies`. |
+| `graph` | Select a numeric or labelled-set field from a public graph SDK result. |
+| `validate` | Select a validator check status or numeric detail. |
+| `health` | Select a health check status, numeric detail, or labelled set. |
+| `history` | Count immutable events by operation, author, harness, or model. |
+| `links` | Count items with present or missing file, test, or documentation evidence. |
+| `derived` | Combine numeric measurements with deterministic arithmetic and cycle detection. |
+| `provider` | Delegate a measurement to an explicitly supplied host/package resolver. |
+
+Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
+
+Assertions require exactly one polarity:
+
+- `ceiling`, `floor`, `equals`, or `zero`
+- `monotone_nondecreasing` or `monotone_nonincreasing`
+- `subset_of` for labelled sets
+
+Scopes are `all`, `active`, or `filter`. A filter names another measurement whose contributors define the item population. `lifetime: hold` keeps the guarantee after its owner item becomes terminal. `lifetime: retire` retires it only after owner termination and requires `retire_reason`.
+
+Enforcement is `block`, `warn`, or `observe`. Weakening a bound, scope, lifetime, owner, source measurement, or enforcement requires `authorization_decision` naming a terminal Decision item verified by the host. The transport verifies only that explicitly named item; it never treats unrelated workspace Decisions as authorization. Tightening does not require authorization.
+
+## CLI Workflow
+
+Create a measurement:
+
+```bash
+pm assurance put measurement active-issues \
+  --definition '{"id":"active-issues","source":{"kind":"items","statuses":["open","in_progress"],"types":["Issue"]},"max_cost":5000}' \
+  --message "Track the active issue population"
+```
+
+Create an assertion with executable negative controls:
+
+```bash
+pm assurance put assertion active-issues-ceiling \
+  --definition '{"id":"active-issues-ceiling","measurement_id":"active-issues","owner_item_id":"pm-example","scope":{"kind":"active"},"ceiling":25,"lifetime":"hold","enforcement":"block","negative_control":{"cases":[{"observed":25,"expected":"pass"},{"observed":26,"expected":"fail"}]}}'
+```
+
+Create and evaluate a gate:
+
+```bash
+pm assurance put gate release-readiness \
+  --definition '{"id":"release-readiness","assertion_ids":["active-issues-ceiling"],"triggers":["ci","pre-release"]}'
+
+pm assurance run release-readiness --trigger ci --dry-run --json
+pm assurance run release-readiness --trigger pre-release --tree "$(git rev-parse HEAD)" --json
+pm assurance verdicts release-readiness --limit 20 --json
+```
+
+Registry reads and removals use the same nouns:
+
+```bash
+pm assurance list measurement --json
+pm assurance show assertion active-issues-ceiling --json
+pm assurance remove gate release-readiness
+```
+
+Referenced measurements and assertions cannot be removed. Remove the consuming gate or assertion first.
+
+## SDK and MCP
+
+The reusable client exposes the same action grammar:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: ".agents/pm" });
+
+await pm.assurance({
+  action: "run",
+  id: "release-readiness",
+  trigger: "ci",
+  dry_run: true,
+});
+```
+
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. A host contributes provider measurements by passing stable resolver ids to `createAssuranceWorkspaceContext`; an absent resolver fails loudly. External adapters must enforce an appropriate timeout. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+
+Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, or `verdicts`. Discover the current machine contract instead of copying parameter lists:
+
+```bash
+pm contracts --action assurance --schema-only --json
+pm contracts --command assurance --flags-only --json
+```
+
+## Verdict Contract
+
+A gate emits one object containing:
+
+- gate id, evaluated tree, trigger, timestamp, and dry-run status;
+- overall `pass`, `warn`, or `block` plus stable exit code;
+- every assertion's measurement, scope, population, observed value, structured bound, signed distance, enforcement, negative-control proof, cost, and contributors;
+- an aggregate compute receipt.
+
+Dry runs never write history. Non-dry verdicts are immutable workspace audit events and remain queryable after ordinary registry changes. Verdict reads return newest entries first and default to a bounded result; use `--limit` to select up to 1,000 matching records. A blocking verdict exits non-zero; warnings and observations remain successful while preserving their failed assertion rows.
+
+## Safety and Evolution
+
+- Use stable lowercase ids; prose belongs in descriptions and mutation messages.
+- Prefer saved measurements and derived arithmetic over duplicating queries in scripts.
+- Give expensive graph, health, validate, or provider measurements explicit cost ceilings.
+- Keep owner items and authorization Decisions linked into the project graph.
+- Treat negative controls as part of the policy, not test decoration.
+- Use `hold` unless a time-bounded guarantee has an explicit retirement rationale.
+- Use `--dry-run` while authoring or tightening a gate, then persist a verdict against an immutable tree.

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,15 @@ 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.
+- [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
 - [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 +78,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/RELEASING.md

@@ -106,7 +106,7 @@ The pipeline performs:
 1. change detection + one-release-per-day guard
 2. a single `YYYY.M.D` version bump; ordinal targets and the removed
    `--allow-same-day-release` override fail closed
-3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version` with `--all-release-tags` so the pending release section matches post-tag CI checks
+3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version`, `--all-release-tags`, and the canonical `--exclude-tag changelog-exclude` policy so the pending release section matches post-tag CI checks
 4. build, clone-local merge-driver installation, then the remaining strict gates (typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate); this ordering makes the checkout-owned CLI available before bootstrap, matches CI, and prevents fresh-clone tracker measurements from observing undeclared merge-driver repairs
 5. release note generation from changelog + pm evidence
 6. commit and tag creation (plus optional push)
@@ -265,7 +265,10 @@ git push origin v<version>
 - build, clone-local merge-driver installation, typecheck, test, and coverage
 - generated changelog verification and `pm-changelog` installation before the
   tracker-bearing static gate, so a clean checkout does not misclassify the
-  managed extension's linked files as missing
+  managed extension's linked files as missing. Recovery of an unpublished
+  immutable tag regenerates only `CHANGELOG.md` with the tagged checkout's
+  canonical package script and fails if that operation changes any other
+  tracked source path (apart from managed-extension install metadata).
 - 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; `--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.
@@ -350,9 +353,10 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   existing version keeps the reviewed dispatch-time `main` source and cannot
   be republished. A definitive missing-version response pins the checkout to
   the existing immutable tag, reapplies the version guard, installs the managed
-  changelog extension before tracker measurement, and permits first publication
-  only from that exact tagged source. Other registry failures stop before
-  source selection or publication.
+  changelog extension, regenerates the package changelog with the tagged
+  checkout's canonical policy under a tracked-path mutation guard, and permits
+  first publication only from that tagged source. Other registry failures stop
+  before source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.

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,8 @@ 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; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
 - 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 +1282,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
@@ -3255,12 +3275,28 @@ For SDK and automation consumers, the key runtime change is the optional `recove
 - `normalized_args`
 - `provided_fields`
 - `missing`
+- `allowed_values`
+- `candidate_commands`
+- `candidate_commands_total`
+- `candidate_commands_truncated`
 - `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.
+
+Unknown-option envelopes rank command paths that accept the rejected flag by
+shared vocabulary and include explicit total/truncation metadata. They are
+contract-discovery hints, not permission to change the requested operation.
+Unknown positional subcommands expose the complete `allowed_values` vocabulary
+and use `suggested_retry` only when a deterministic nearby value exists.
 
 ## Authoring Pattern
 

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -85,24 +85,53 @@ values are ignored instead of polluting analytics. Presence-only harness flags,
 including `CLAUDE_CODE_CHILD_SESSION=1`, are detection evidence and are never
 persisted as semantic roles.
 
-For ordinary CLI mutations, the detector can infer an `implementer` or
-`reviewer` role from the bounded command verb and a topic from an explicit
-`pm-...` item argument. Explicit overrides, session declarations, and trusted
-host declarations retain precedence over this inference.
+## Infer semantic context from lifecycle state
+
+Successful `claim`, `release`, and `focus` operations maintain a bounded,
+checkout-local semantic workset. Later CLI and SDK mutations can therefore
+record useful role and topic provenance without repeating identity flags or
+retaining prompt text:
+
+- a claim records the item and at most 16 canonical parent ancestors, infers
+  `role=implementer`, and uses the item or stable multi-item workset as topic;
+- an explicit focus becomes the high-confidence topic and infers
+  `role=planner`;
+- a release removes only that claim and records `role=release-operator` while
+  other active claims remain; and
+- clearing the final claim and focus removes the inferred session record.
+
+At most 64 active item ids and 32 evidence rows are retained. Multi-item topics
+are deterministically bounded and hashed when their full identity would exceed
+the provenance limit. The state is partitioned by the privacy-safe agent
+instance when available, otherwise by a truncated hash of the resolved author.
+It lives in the gitignored runtime session file and malformed records fail open.
+
+The same workset feeds `pm context` as `claim_focus` relevance: claimed and
+focused items receive affinity `1`, while bounded canonical ancestors receive
+`0.75`. Active work is preserved by the context packer under its existing token
+ceiling; the inference never raises the requested budget.
+
+Explicit overrides, declared session context, command flags, environment,
+MCP-client declarations, host declarations, and configured probes all retain
+precedence. Automatic observations use `source=inferred`, `rule_version=v2`,
+and carry the bounded claim/focus/lineage evidence that supports them. The pure
+`semanticAttributionAffinity()` helper and lifecycle recording primitives are
+public SDK exports for custom hosts.
 
 ## Diagnose missing provenance
 
 `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
@@ -144,6 +173,11 @@ declared a dimension but supplied no value. The compatibility helper
 `summarizeAgentModelProvenance(entries)` remains available for model-only
 consumers.
 
+`evaluateSemanticAttributionCoverage(entries, options)` groups role/topic
+availability by harness and precedence source. Its explicit minimum-entry and
+minimum-coverage ratchet fails empty corpora, making a negative control part of
+the contract instead of allowing an unobserved harness to pass vacuously.
+
 `groupHistoryByEpisode(entries)` returns deterministic nested groups:
 
 - recorded episode keys produce `source: "declared"`;
@@ -165,3 +199,6 @@ channel. Do not put tokens, private hostnames, signed URLs, or raw external
 payloads in ids, labels, roles, or topics. Session ids used to derive
 `agent_instance` remain transient and are not persisted. Every new history
 field is optional, so existing streams and packages remain readable.
+Automatic semantic attribution is likewise restricted to item ids, controlled
+roles, rule metadata, and canonical lineage ids. It never persists argv,
+environment values, prompts, filesystem contents, or raw harness session ids.

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: