@unbrained/pm-cli 2026.9.5 → 2026.9.6

package/docs/BOUNDED_CONTEXT_READS.md

@@ -0,0 +1,185 @@
+# Bounded context reads and duplicate discovery
+
+Tracked by [pm-pshhry](../.agents/pm/issues/pm-pshhry.toon),
+[pm-ydshl9](../.agents/pm/issues/pm-ydshl9.toon),
+[pm-bab3gb](../.agents/pm/issues/pm-bab3gb.toon),
+[pm-fx80w2](../.agents/pm/issues/pm-fx80w2.toon),
+[pm-gtw5zh](../.agents/pm/issues/pm-gtw5zh.toon), and
+[pm-s8ybl9](../.agents/pm/issues/pm-s8ybl9.toon).
+
+Project management is context management. Routine reads should pay for the
+requested evidence, and derived feedback should not grow with every candidate
+in a project's history. These primitives share SDK implementations across CLI,
+MCP, and package consumers.
+
+## Point reads
+
+`pm get <id>` at standard depth reads the addressed item and its own history.
+It does not enumerate unrelated items to compute child counts. `--depth brief`
+and `--fields id,title` also omit claim-history work and heavy output facets.
+The cost still depends on the addressed record, registered type directories,
+and extension activation; this is not a constant-latency guarantee for arbitrary
+extensions or unbounded individual history streams.
+
+Request hierarchy work explicitly with `--fields id,children`, `--tree`, or a
+deep/full container read. These paths preserve registered hierarchy semantics,
+including inverse and custom relationship kinds, rather than treating only the
+scalar `parent` field as authoritative. An omitted `children` facet carries a
+restore selector in the omission receipt. Explicit deep/full and child-field
+projections retain a zero-count rollup for an empty container.
+
+Caller-carried output sessions retain only portable item identities in
+`next_state.seen_item_ids`. Workspace activity such as `_workspace` remains
+visible in full on subsequent reads. It cannot become an invalid item reference
+or make the next read reject a state produced by the previous read.
+
+The optional SQLite projection binds each FTS document to the corresponding
+`items.rowid`. Maintenance resolves the indexed item identity and deletes the
+single FTS row, avoiding a scan of the unindexed FTS `id` column on every insert,
+update, or deletion. Derived index version 5 rejects older projections and
+rebuilds them from authoritative metadata. Real SQLite query-plan tests retain
+the old predicate as a negative control and verify search results after updates
+and deletions. SQLite documents the distinction between
+[FTS columns and row identity](https://www.sqlite.org/fts5.html).
+
+## Exact duplicate candidates
+
+```bash
+pm duplicates --status all --threshold 0.8 --json
+pm duplicates --status open --exhaustive --json
+```
+
+The default algorithm orders title tokens by corpus frequency and uses a
+Jaccard prefix join. For a set of size `n` and threshold `t`, a prefix of length
+`n - ceil(t*n) + 1` must intersect the similarly ordered prefix of every
+qualifying set. The length filter rejects impossible token matches before
+scoring. Exact normalized titles, issue codes, and empty-token matches retain
+the canonical scorer's separate rules. This follows the established
+[all-pairs similarity-search approach](https://research.google/pubs/scaling-up-all-pairs-similarity-search/).
+
+Both modes retain exact recall relative to the canonical title scorer.
+`cost` discloses `algorithm`, `item_count`, `possible_pairs`, `candidate_pairs`,
+`scored_pairs`, `pair_limit`, and `recall_guarantee`. The one-million-candidate
+safety ceiling remains enforced. Dense duplicate output or a zero threshold
+can still require quadratic work; the command refuses without returning a
+partial answer. Exact recall is not a claim that every semantic duplicate has
+similar titles. Review the actual item evidence before merging or closing.
+
+Packages with remote or custom stores can use the same kernel without building
+a filesystem tracker:
+
+```ts
+import { analyzeDuplicateItems } from "@unbrained/pm-cli/sdk/query";
+
+const result = analyzeDuplicateItems([
+  { id: "work-a", title: "Publish research protocol", type: "Task", status: "open" },
+  { id: "work-b", title: "Publish research protocol", type: "Task", status: "closed" },
+]);
+console.log(result.clusters, result.cost);
+```
+
+The function preserves its input, validates unique nonempty identifiers, and
+returns deterministic components and scored pair evidence. The filesystem
+`findDuplicateClusters`, `PmClient.duplicates`, CLI and MCP adapters reuse it.
+Record the algorithm and cost receipt in create-time duplicate-check evidence.
+
+## Feedback storage
+
+Serving receipts retain the full candidate population in memory for final
+delivery validation. Persisted events retain only the first 256 candidate rows,
+with explicit population and omission counts. Only sampled ids observed in the
+final emitted result can train affinity. This deterministic sample has no
+unbiased-propensity claim. Unknown row properties are not persisted.
+
+`CONTEXT_USAGE_LIMITS` publishes a 256 KiB physical ceiling, a 32 KiB individual
+event ceiling, 2,048 retained events and a 30-day default horizon. Writers share
+a cross-process lock. High-water compaction atomically replaces the ledger with
+a suffix of at most half the byte ceiling, leaving append headroom. Readers
+consume at most the byte ceiling even for an oversized legacy file. Custom
+retention controls can tighten the limits; invalid controls fail before I/O.
+
+Serving receipt `storage` reports actual `written_bytes`, `ledger_bytes`,
+`compacted`, and `lock_wait_ms`. Written bytes count ledger data rather than lock
+metadata or filesystem block allocation. The receipt is attached to results
+through a non-JSON symbol and does not inflate normal CLI output. Storage is
+derived and disposable; item history remains independent. Ledger access refuses
+existing symbolic links, shared hard links, non-regular files, and a redirected
+runtime directory. Appends use a validated descriptor with no-follow opening
+where supported; replacement files are created exclusively with private
+permissions. Compaction closes both data handles before replacing the ledger,
+including on Windows.
+
+Feedback persistence requires trusted, stable workspace directory entries and
+ancestors. It is unsafe when an untrusted actor can concurrently replace those
+entries: portable Node filesystem APIs do not pin ancestor directories through
+the whole operation. The link checks reject existing redirections; the lock
+coordinates cooperating SDK writers and is not a security boundary. Before
+using an adversary-writable live workspace, set `PM_CONTEXT_USAGE_DISABLED=1`
+to disable feedback reads and writes, or work in an isolated copy owned by the
+caller. Public feedback API callers can also pass `enabled: false`.
+
+## Reproducible measurements
+
+```bash
+pnpm build
+node scripts/bench/context-read-costs.mjs 10000 100000 1000000
+node scripts/bench/point-read-costs.mjs 100 10000 100000
+```
+
+The script uses paired titles with common project vocabulary, compares a
+1,000-item subset against exhaustive scoring, and runs four concurrent writers
+for 40 serves per tier in temporary storage. It asserts exact reference equality,
+expected pair counts, reachable byte ceilings, and append headroom. Property
+tests additionally vary thresholds, Unicode, punctuation, and issue identifiers.
+
+The point-read script holds the addressed Epic constant while varying corpus
+size. The public `measureItemMetadataReadWork` query SDK wrapper reports actual
+item-store enumeration calls and returned metadata rows, including cache hits.
+Ordinary reads must perform zero enumerations; an explicit child scan must
+observe every generated item. A regression test deliberately enumerates and
+discards the corpus before a normal read, proving that output shape alone cannot
+satisfy this work gate. Measurements preserve operation failures, isolate
+concurrent roots, include nested work, and release their observers on completion.
+They cover item-store enumeration APIs rather than arbitrary extension I/O.
+Fixture setup
+registers all generated types, including `Story`, through the live SDK schema
+and uses deterministic SDK execution for byte-reproducible workspace history.
+
+The 2026-09-05 filesystem run observed the following timings (10 reads per
+projection, including feedback writes). The explicit scan includes the cold
+derived-index rebuild; these are host observations rather than latency gates.
+
+| Corpus items | Standard p95 | Brief p95 | Fields p95 | Explicit full scan | Verified scan rows |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 100 | 4.53 ms | 4.24 ms | 3.54 ms | 48 ms | 100 |
+| 10,000 | 3.61 ms | 3.03 ms | 4.08 ms | 4.91 s | 10,000 |
+| 100,000 | 3.69 ms | 11.00 ms | 3.11 ms | 48.59 s | 100,000 |
+
+Measured on 2026-09-05 with Node 26.7.0; these are observations, not portable
+latency guarantees. Duplicate timings exclude filesystem ingestion.
+
+| Items | Possible pairs | Scored pairs | Analysis time | Mean bytes written per serve | Compactions / serves | Final ledger bytes |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 10,000 | 49,995,000 | 5,000 | 92 ms | 18,138 | 2 / 40 | 237,785 |
+| 100,000 | 4,999,950,000 | 50,000 | 864 ms | 18,149 | 2 / 40 | 237,821 |
+| 1,000,000 | 499,999,500,000 | 500,000 | 10,367 ms | 18,135 | 2 / 40 | 237,857 |
+
+The same four-writer runs include full in-memory candidate validation and final
+delivery recording. Throughput therefore still falls with candidate population.
+
+Lock-wait percentiles use the empirical nearest rank across all 40 serving
+receipts; these are four concurrent tasks sharing a cross-process lock, not a
+measurement of four separate OS processes.
+
+| Candidate rows per serve | Serves/s/workspace | Minimum wait | p50 wait | p95 wait | Maximum wait |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 10,000 | 46.73 | 3.11 ms | 25.15 ms | 84.97 ms | 105.66 ms |
+| 100,000 | 20.82 | 18.29 ms | 50.10 ms | 193.86 ms | 229.60 ms |
+| 1,000,000 | 1.92 | 198.10 ms | 809.52 ms | 1,367.67 ms | 1,622.77 ms |
+
+Reference recall was 100% at every tier. The million-item batch does not meet
+the broader one-second project target; persistent incremental ingestion and
+analysis remain necessary for that target. Full candidate validation still
+costs O(candidate count) in memory even though persisted feedback is bounded.
+On the live 2,638-item corpus, default discovery completed after scoring 3,136
+of 3,478,203 possible pairs; the prior algorithm refused at its safety ceiling.

package/docs/CLOSE_EVIDENCE_RECOVERY.md

@@ -0,0 +1,35 @@
+# Recovering missing close evidence
+
+Tracked by [pm-ub1ott](../.agents/pm/issues/pm-ub1ott.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
+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
+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.
+
+For example, when only the actual outcome is missing, the recovery arguments
+contain `--actual-result` alone (plus the item and tracker selection):
+
+```bash
+pm --pm-path <tracker-root> update <item-id> \
+  --actual-result "Evidence update appended; original close event unchanged"
+```
+
+An attempt to close an already terminal item also returns evidence-update
+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 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.

package/docs/COMMANDS.md

@@ -173,12 +173,18 @@ Use `context` first for a compact active-work snapshot. Use `search` when the re
 Use `duplicates --status all` for a true whole-history duplicate check. The
 result echoes `filters.statuses: null` for the unrestricted corpus; named or
 custom statuses are normalized through the runtime status registry and an
-unknown status fails instead of returning a false-clean result.
+unknown status fails instead of returning a false-clean result. The default
+lossless prefix filter preserves every pair that meets the canonical similarity
+threshold. `--exhaustive` compares all pairs for small-corpus verification. Both
+modes disclose the algorithm, possible and scored pair counts, exact recall
+guarantee, and safety ceiling; exceeding that ceiling refuses without returning
+a partial result. Review clusters before closing anything: title similarity is
+evidence for investigation, not proof that work is interchangeable.
 As a read-only structured surface, `duplicates` accepts the universal output
 controls, including `--output-format json`, `--lean`, projection/amount
 controls, and token accounting, while its default TOON output remains bounded.
 Tracked by [pm-gh1076](../.agents/pm/issues/pm-gh1076.toon).
-Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. The universal `--output-include` selector can request stored collections directly, for example `pm get <id> --output-include comments,learnings,tests`; the same bare and `item.<field>` grammar works through CLI, SDK, and MCP transports. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
+Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. The universal `--output-include` selector can request stored collections directly, for example `pm get <id> --output-include comments,learnings,tests`; the same bare and `item.<field>` grammar works through CLI, SDK, and MCP transports. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Standard reads of every item type avoid a workspace child scan. For container-oriented built-ins (Epic, Feature, Milestone, and Plan) and custom types, `--depth deep|full` adds type-agnostic child counts, a bounded sample, and continuation metadata. An explicit `--fields id,children` requests that rollup for any type. See [bounded context reads](BOUNDED_CONTEXT_READS.md) for the cost contract. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
 When the strongest duplicate match is terminal because the same work recurred,
 reuse its lineage instead of creating or copying another item:
@@ -526,7 +532,7 @@ pm notes <id> --event-type step.completed --since 2026-07-31T00:00:00Z --include
 
 `append` mutates the scalar Markdown body and is not a concurrency-safe event log. `notes --add` stores union-merged text entries; `notes --add-json` stores a validated JSON payload plus timestamp and author in that same merge-safe collection. Structured events retain canonical JSON text for older readers and expose `format: json`, `data`, and optional `event_type` to SDK/CLI/MCP consumers. `--since`, `--event-type`, `--limit`, and `--include-meta` provide bounded reads without client-side free-text parsing.
 
-can make non-lifecycle metadata updates and append comments, linked files, and linked
+`pm update` can make non-lifecycle metadata updates and append comments, linked files, and linked
 docs in one audited history entry. It is intentionally append-only for evidence:
 lifecycle/ownership fields, dependencies, tests, notes, learnings, reminders, events,
 and all clear/replace operations stay restricted or use their dedicated commands.
@@ -760,7 +766,7 @@ pm deps <id> --format context --direction both --kind blocked_by,parent --token-
 
 Linked files and docs keep reviews reproducible. `deps` is read-only and projects item relationships. Tree and graph formats are bounded by depth, node, edge, and estimated-token budgets (safe defaults: depth 32, 200 nodes, 400 edges, 16,000 tokens); pass `--max-depth`, `--node-limit`, `--edge-limit`, or `--token-budget` to tighten them. A bounded result carries deterministic `truncation.reasons`, effective limits, full unique-node/edge totals, and omitted counts. The estimate is calculated from the emitted JSON or TOON representation, including its accounting envelope. `--format context` returns one bounded, explainable relationship packet: a counts-first summary, per-node `role`/`via`/`reasons`, root evidence pointers, enumerated `missing_references` with active-versus-legacy classification, `meta.completeness`, exact rendered `meta.usedTokens`, and cursor continuation; `--direction`, repeatable or comma-separated `--kind`, and `--cursor` further control that traversal (see [Relationship Graph](RELATIONSHIP_GRAPH.md)). `--edge-limit` caps both returned graph edges and enumerated `missing_references`; `missing_reference_count` retains the total when rows are omitted. The standalone `--note <text>` flag annotates every link added by `--add`/`--add-glob` in the same invocation (a per-entry embedded `note=` wins); `--note` without an add is a usage error.
 
-Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; create/update `--dep` accepts `id,kind,type,author,created_at,source_kind`; `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Set `source_kind=global` for a dependency owned by another workspace: pm preserves its id verbatim, materializes it as an external graph endpoint, and excludes it from dangling-local-reference findings. Dependencies without that explicit provenance retain normal local `id_prefix` normalization. Bare values (`--add src/cli/main.ts`) skip key validation.
+Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; create/update `--dep` accepts `id,kind,type,author,created_at,source_kind`; `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Set `source_kind=global` for a dependency owned by another workspace: pm preserves its id verbatim, materializes it as an external graph endpoint, and excludes it from dangling-local-reference findings. Explicit remote locators also retain their spelling; other dependency and parent references share local `id_prefix` normalization, including uppercase and `#` shorthand. Bare values (`--add src/cli/main.ts`) skip key validation.
 
 ## Graph Queries
 
@@ -886,7 +892,11 @@ pm gc --scope locks --dry-run
 
 Use dry-run modes before broad lifecycle or cleanup changes.
 
-`pm gc` accepts `--scope` values `index`, `embeddings`, `runtime`, `locks`, and `checkpoints` (comma-separated or repeatable); with no `--scope` it sweeps all of them. The `runtime` scope clears `runtime/test-runs/` and `runtime/history-drift-cache.json`; removing the drift cache forces the next `pm health` run to perform a full history-drift re-scan. The `embeddings` scope removes the keyword/semantic index artifacts (`search/embeddings.jsonl`, `search/vectorization-status.json`, `search/lancedb/`) **and** the background-refresh queue (`search/pending-refresh.json`) and its gate so a worker draining a stale queue cannot rebuild a partial index against an empty ledger; it invalidates the entire semantic index, so run `pm reindex --mode keyword` (and `--mode semantic` when enabled) afterwards. The `locks` scope removes only **expired** lock files in `locks/` — those whose own embedded `created_at + ttl_seconds` has elapsed (debris left by crashed processes). Active locks and any lock file that cannot be parsed are always retained (never deleted when staleness cannot be proven), and the result includes a `locks` summary (`scanned`/`removed`/`retained`).
+`pm gc --scope` accepts `index`, `embeddings`, `runtime`, `locks`, and `checkpoints`, comma-separated or repeated. Omitting the flag selects all scopes:
+
+- `runtime` clears `runtime/test-runs/` and `runtime/history-drift-cache.json`. The next health check rescans history drift.
+- `embeddings` removes keyword/semantic artifacts (`search/embeddings.jsonl`, `search/vectorization-status.json`, `search/lancedb/`) plus `search/pending-refresh.json` and its gate, preventing a background worker from rebuilding a partial index against an empty ledger. Rebuild with keyword reindex and semantic reindex when enabled.
+- `locks` removes only provably expired locks, using embedded `created_at + ttl_seconds`. Active, unreadable, or unparseable locks remain. The result reports `scanned`, `removed`, and `retained` counts.
 
 The `checkpoints` scope prunes bulk-mutation rollback checkpoints under `checkpoints/` (written by `pm update-many`/`pm close-many`) that are older than `checkpoints.retention_days` (default 14; set via `pm config <scope> set checkpoints_retention_days <n>`). Checkpoints whose `created_at` cannot be parsed are retained (safety-first, like the locks sweep), and the result includes a `checkpoints` summary (`scanned`/`removed`/`retained`/`retention_days`). Removing aged checkpoints permanently closes their `--rollback` window.
 
@@ -894,7 +904,7 @@ The `checkpoints` scope prunes bulk-mutation rollback checkpoints under `checkpo
 
 `pm validate --check-metadata` also groups missing-required-field counts per item type in `details.missing_by_type` (for example `{ "Task": { "close_reason": 3 } }`) — counts only, zero-suppressed, and limited to the active metadata profile's required fields, so remediation can be targeted by type without verbose row dumps.
 
-`--counts` keeps the validation envelope, check statuses, warning codes, scalar counts/totals, nested count maps, and fix summary totals while recursively omitting diagnostic and fix row arrays. It is the preferred agent projection when deciding whether drift exists; remove it only when the affected ids or remediation rows are needed. The public SDK `projectValidateCounts` helper applies the identical projection to an already-computed `ValidateResult`.
+`--counts` keeps the validation envelope, check statuses, warning codes, scalar counts/totals, nested count maps, and fix summary totals while recursively omitting diagnostic and fix row arrays. False `*_truncated` markers are omitted; true markers, other false values, and zero counts remain. It is the preferred agent projection when deciding whether drift exists; remove it only when the affected ids or remediation rows are needed. The public SDK `projectValidateCounts` helper applies the identical projection to an already-computed `ValidateResult`.
 
 By default the human view caps each diagnostic `*_item_ids` list at 5 entries and sets the matching `*_truncated` flag. `--json` **never** truncates those lists (machine consumers always receive the complete arrays), and `--all-affected-ids` (equivalent to `--verbose-diagnostics`) emits the full lists in human mode too — so bulk remediation can pipe every affected id straight into `pm update-many`:
 
@@ -903,13 +913,25 @@ pm validate --check-metadata --all-affected-ids
 pm validate --check-metadata --json | jq -r '.checks[] | select(.name=="metadata") | .details.missing_acceptance_criteria_item_ids[]'
 ```
 
-`--auto-fix` applies the safe, deterministic subset of those remediations automatically and reports the result under a top-level `fixes` object (`planned_fixes[]`, `applied_fixes[]`, `gated_fixes[]`, `failed_fixes[]` — each row lists the item id, check, field, and the equivalent standalone `pm` command). Safe means derivable and non-destructive: a closed item missing `resolution` is backfilled from its own `close_reason` (or the `"completed"` default), and a closed item missing `close_reason` is backfilled from its existing `resolution`. Auto-fix NEVER closes, cancels, or deletes items, and every applied fix runs through the normal audited `pm update` path. Two scopes are opt-in. Structural lifecycle fixes — an active item whose parent is terminal gets reparented to its active grandparent or has its parent link cleared — are always _planned_ but only _applied_ under an explicit `--fix-scope lifecycle`. Estimate backfills — an item missing `estimated_minutes` gets a config-driven per-type default — are likewise _planned_ but only _applied_ under `--fix-scope estimates` (estimates are heuristic per-type guesses, not derived facts, so they are never auto-granted). The defaults are `Epic`/`Milestone` 2880, `Feature`/`Story` 480, `Task`/`Plan` 120, `Issue`/`Bug` 60, `Chore` 30, `Decision` 15, and a 120-minute fallback for any other type; override them per type with the `validation.estimate_defaults_by_type` setting (a `{ "<Type>": <minutes> }` map). `--fix-scope` is an exact allowlist of what `--auto-fix` may mutate (`metadata`, `resolution`, `estimates`, `lifecycle`; comma-separated or repeatable) — `--fix-scope estimates` alone applies _only_ estimate fixes; omitting the flag grants the safe field-backfill scopes (`metadata`, `resolution`) and neither estimates nor lifecycle. `--dry-run` previews the full plan without mutating anything. With `--auto-fix` and no explicit `--check-*` flags, only the fix-capable checks (metadata, resolution, lifecycle) run. The `checks` in the output always describe the pre-fix state; re-run `pm validate` to confirm convergence.
+`--auto-fix` reports `planned_fixes`, `applied_fixes`, `gated_fixes`, and `failed_fixes` under `fixes`. Each row identifies the item, check, field, and equivalent standalone command:
+
+- Safe field backfills derive a missing terminal `resolution` from `close_reason` (falling back to `"completed"`) or a missing `close_reason` from existing `resolution`. Every applied change uses the audited update path; auto-fix never closes, cancels, or deletes items.
+- `--fix-scope lifecycle` explicitly permits reparenting an active item from its terminal parent to an active grandparent, or clearing that parent link. These structural fixes are otherwise planned only.
+- `--fix-scope estimates` explicitly permits heuristic per-type estimates. Defaults in minutes are Epic/Milestone 2880, Feature/Story 480, Task/Plan 120, Issue/Bug 60, Chore 30, Decision 15, and fallback 120. Override `validation.estimate_defaults_by_type` with a type-to-minutes map.
+- `--fix-scope` is an exact, repeatable or comma-separated allowlist: `metadata`, `resolution`, `estimates`, `lifecycle`. Omitting it grants only the safe metadata/resolution scopes; specifying only estimates grants only estimates.
+- `--dry-run` previews without mutation. With no explicit check flags, auto-fix runs only metadata, resolution, and lifecycle checks. Output checks describe the pre-fix state; rerun validation to confirm convergence.
 
 > Note: acceptance-criteria gaps are intentionally **not** auto-fixed. Unlike resolution/close_reason (derivable from the item's own fields) or estimates (a config-driven type default), acceptance criteria have no deterministic source — synthesizing them from the description would fabricate content rather than derive it, violating the auto-fix safety invariant. They remain `--fix-hints`-only.
 
 `pm validate --check-lifecycle` detects dependency cycles from explicit dependency edges, scalar `blocked_by` item ids, and exact pm-id references in `definition_of_ready`. That catches logical deadlocks such as A blocked by B while B's readiness text names A; `--dependency-cycle-severity off|warn|error` still controls whether those cycles warn, error, or remain informational in details.
 
-`pm validate --check-files` classifies every stale linked path in `details.missing_linked_path_classifications` as either `moved` (a file with the same basename still exists in the scan — the row carries the top relink candidate, e.g. `old/path.md:moved:new/path.md`) or `deleted` (no candidate anywhere, e.g. `old/path.md:deleted`). It also reports `details.missing_linked_path_rows` — owner attribution so cleanup is evidence-based without a reverse lookup. By default these are token-efficient one-liners (`<path>:<classification> owner=<id> status=<status> field=<files|docs> title="…"`); `--verbose-file-lists` expands them to the full structured shape (`{ path, classification, items: [{ id, type, title, status, field }] }`). Orphaned existing files get the same treatment through `details.orphaned_path_classifications` and `details.orphaned_path_rows`; classifications start with `docs_unowned`, `tests_unowned`, `source_unowned`, or `unlinked_existing`, and rows include a concrete `pm docs|files <id> --add ...` hint when a likely owner is found from nearby linked paths. `--prune-missing` bulk-removes the stale links classified `deleted` from their items (link removal only — real files are never touched; `moved` links are kept so their relink candidates are not lost) and reports each removal in `fixes.applied_fixes[]` as the equivalent `pm files <id> --remove <path>` / `pm docs <id> --remove <path>` command. It honors `--dry-run` and implies `--check-files`.
+`pm validate --check-files` joins stale paths, owning items, and relocation candidates in structured `details.missing_linked_path_rows` in both compact and full output:
+
+- `moved` means same-basename candidates exist; these are suggestions requiring verification. `deleted` means none exists. `malformed` marks ambiguous missing CSV or path:note literals and never infers a relocation or prune.
+- Counters distinguish unique paths from linked holder/field pairs, active holders from the closed subset, and all terminal holders. Only active missing paths cause the files warning; historical debt remains visible. Custom lifecycle roles determine the partition.
+- Active paths and owners appear first. Compact output bounds both dimensions and includes total counts and truncation flags; `--verbose-file-lists` restores every row. See [Linked-file repair rows](OUTPUT_PROJECTION_CONTRACTS.md#linked-file-repair-rows) for the SDK contract.
+- Existing unlinked paths retain `orphaned_path_classifications` and `orphaned_path_rows`, with `docs_unowned`, `tests_unowned`, `source_unowned`, or `unlinked_existing` classifications and concrete ownership hints where available.
+- `--prune-missing` removes only links classified `deleted`, retaining moved and malformed references for review. It never removes real files, honors `--dry-run`, implies `--check-files`, and records equivalent files/docs removal commands in `fixes.applied_fixes`.
 
 The default `pm validate` run also includes a `format_version` check that compares every item's stored item metadata format version (`pm_format_version`, absent meaning the implicit baseline version `1`) against the version this pm runtime writes. `details.outdated_items` lists items that predate the current version (a future storage migration would rewrite them — advisory `warn`); `details.ahead_items` lists items written by a _newer_ pm than the one running, which is an `error` because validation cannot vouch for fields it does not understand (upgrade pm to read them safely). At the current baseline version both lists are empty and the check is `ok`. The same `pm_format_version` integrity is surfaced by `pm health` under the `integrity` check (`details.counts.item_outdated_format_version` / `item_ahead_format_version`).
 

package/docs/CONTEXT_RELEVANCE.md

@@ -1,6 +1,6 @@
 # Context relevance and packing
 
-Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon), [pm-07pt16](../.agents/pm/issues/pm-07pt16.toon), [pm-wv47pf](../.agents/pm/issues/pm-wv47pf.toon), [pm-3hps](../.agents/pm/tasks/pm-3hps.toon), and [pm-801d](../.agents/pm/features/pm-801d.toon).
+Tracked by [pm-bab3gb](../.agents/pm/issues/pm-bab3gb.toon), [pm-4k6b](../.agents/pm/features/pm-4k6b.toon), [pm-07pt16](../.agents/pm/issues/pm-07pt16.toon), [pm-wv47pf](../.agents/pm/issues/pm-wv47pf.toon), [pm-3hps](../.agents/pm/tasks/pm-3hps.toon), and [pm-801d](../.agents/pm/features/pm-801d.toon).
 
 `pm context` and `pm next` share one public SDK relevance pipeline. The built-in
 commands assemble authoritative item metadata, load rebuildable signal rows,
@@ -104,9 +104,13 @@ the same explanation as the ranking it serves.
 ### Delivered usage feedback
 
 Usage affinity learns from post-egress delivery rather than pre-budget packing.
-A versioned serve event records the full propensity rows and a correlation id;
-CLI and `PmClient` egress append a delivery event containing the final
-`result_omitted` decision and exact emitted item ids. A whole-result omission
+A versioned serve event records at most 256 candidate rows in input order,
+plus `candidate_count`, `omitted_row_count`, and a correlation id. The SDK
+receipt keeps the complete candidate set in memory to validate final delivery.
+CLI and `PmClient` egress append the final `result_omitted` decision and emitted
+item ids intersected with the recorded sample. Unsampled items produce no
+exposure or affinity judgment; the sample is deterministic, not an unbiased
+propensity estimate. A whole-result omission
 therefore delivers zero items even when the packer selected rows earlier.
 
 Direct `runContext` and `runNext` calls record only their assembled rows on a
@@ -116,6 +120,14 @@ Legacy serve events have no correlation marker, so the affinity reader ignores
 their inclusion flags and reports them as `untrusted_serving_events` instead of
 training on unverifiable phantom serves.
 
+The physical ledger is capped at 256 KiB. Appends exceeding that ceiling compact
+atomically under the writer lock to a suffix of at most 128 KiB, leaving headroom
+for subsequent requests. Reads consume at most 256 KiB even for oversized legacy
+files, dropping a partial first row. Age and event-count limits also apply.
+`CONTEXT_USAGE_LIMITS` and serving receipt `storage` expose the ceilings, actual
+written bytes, retained bytes, compaction decision, and lock wait to SDK hosts.
+See [bounded context reads](BOUNDED_CONTEXT_READS.md) for cost measurements.
+
 For corpora of at least 10,000 items, `context` automatically allocates a
 bounded fraction of its token budget to recent calendar-epoch and epic-lineage
 rollups. `search` attaches only matching rollups. The projection contains

package/docs/DEFECT_RECURRENCE.md

@@ -1,16 +1,17 @@
 # Defect Recurrence and Boundary Evidence
 
-Tracked by [pm-1qkivy](../.agents/pm/features/pm-1qkivy.toon), [pm-rtn5h6](../.agents/pm/tasks/pm-rtn5h6.toon), [pm-0pzgit](../.agents/pm/tasks/pm-0pzgit.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+Tracked by [pm-1qkivy](../.agents/pm/features/pm-1qkivy.toon), [pm-rtn5h6](../.agents/pm/tasks/pm-rtn5h6.toon), [pm-0pzgit](../.agents/pm/tasks/pm-0pzgit.toon), [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
 
 ## Agent Quick Context
 
 `pm` treats project management as context management. A resolved defect is therefore not only a closed item: it is durable context that should select the checks most likely to prevent the same failure from recurring.
 
-The public SDK now provides three composable contracts:
+The public SDK provides four composable contracts:
 
 - a captured-boundary registry that rejects self-generated fixtures, unsafe samples, missing samples, and expired waivers;
 - a defect-evidence ratchet that requires a typed escape class plus a gate improvement or reviewed, expiring waiver on new terminal defects;
-- a versioned recurrence index that maps proposed files, packages, PM items, tags, and error codes to shared local and hosted checks.
+- a versioned recurrence index that maps proposed files, packages, PM items, tags, and error codes to shared local and hosted checks;
+- a complete-population recurrence coverage report with bounded, resumable evidence rows.
 
 The CLI and MCP use the same SDK action path. Repository policy can be replaced by a package or workspace policy without changing the analyzer.
 
@@ -63,7 +64,8 @@ Use `pm assurance risk` for an operator or agent decision. Use the pure SDK func
 
 ### TypeScript compatibility
 
-The exported `ASSURANCE_ACTIONS` tuple and `AssuranceActionResult` union now include `risk` and `DefectChangeRiskReport`. This is additive at runtime, but TypeScript consumers with an exhaustive action or result switch must add the new branch. The SDK surface snapshot records that source-compatibility change explicitly.
+The exported `ASSURANCE_ACTIONS` tuple and `AssuranceActionResult` union include `risk`, `lineages`,
+`DefectChangeRiskReport`, and `DefectRecurrenceCoverageReport`. This is additive at runtime, but TypeScript consumers with an exhaustive action or result switch must add the new branch. The SDK surface snapshot records that source-compatibility change explicitly.
 
 ## Policy Model
 
@@ -79,7 +81,69 @@ The repository example is [config/defect-recurrence-policy.json](../config/defec
 
 Repository policy validation rejects duplicate ids, absent historical examples, missing family negative controls, invalid taxonomy values, and budgets outside zero through one. Deterministic sorting makes the serialized policy merge-friendly.
 
-Register a family whenever a defect is recorded as a recurrence of an earlier one, meaning the new item carries a `recurs_from` edge to its predecessor. A recurrence with no family produces no local and no hosted protection, so the next instance is rediscovered by hand. Coverage of recorded recurrence lineages is not yet computed by any gate; that gap is tracked on [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon).
+Register a semantic family seed using its owner, trigger item ids, or historical
+item ids. The SDK follows every recorded local `recurs_from` edge in either
+direction to derive family membership for the complete connected lineage.
+Cycles and deep chains do not impose a traversal cutoff. Related, parent, and
+external edges never establish recurrence coverage; tags and matching file
+globs select change risk but cannot certify lineage registration.
+
+Derived members inherit the family's checks. Changes naming a member or one of
+its exact project-scoped linked files select those checks even when the policy
+never named that member. Incremental indexes retain sparse direct evidence so
+removing or changing an edge also removes obsolete inherited matches.
+
+### Complete-population coverage
+
+Tracked by [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon).
+
+```ts
+import { analyzeDefectRecurrenceCoverage } from "@unbrained/pm-cli/sdk/governance";
+
+const coverage = analyzeDefectRecurrenceCoverage(policy, allStatusItems, {
+  limit: 25,
+  uncoveredOnly: true,
+});
+```
+
+Supply an authoritative complete item corpus. The workspace action loads it
+with strict read semantics. Unreadable item documents or directories refuse
+both workspace analyses and the repository gate with `list_source_incomplete`.
+Embedding hosts can request the same policy with
+`createAssuranceWorkspaceContext(pmRoot, { strict_read: true })`.
+Duplicate ids are rejected. Missing local targets
+remain in the population and produce `missing_recurrence_item`; an unregistered
+component produces `unregistered_recurrence_item`. The complete verdict is
+computed before filtering or pagination, so a covered first page cannot hide
+an uncovered member later in the graph.
+
+```bash
+lineage_request=$(jq -cn --slurpfile policy config/defect-recurrence-policy.json \
+  '{policy:$policy[0],limit:25,uncoveredOnly:true}')
+pm assurance lineages --definition "$lineage_request" --json
+```
+
+SDK, CLI, and MCP accept the same `definition`. Use `limit` from 1 through 100,
+`cursor`, and `uncoveredOnly` inside that object. Continuations bind the policy,
+complete recurrence evidence, item presence, and filter; changing page size is
+allowed. `total`, `has_more`, and `next_cursor` describe the selected rows;
+`population` always describes every recorded recurrence member. The CLI analysis
+returns a report; the repository gate makes its `ok` predicate blocking.
+
+The denominator includes covered, uncovered, and missing recurrence ids across
+all lifecycle states. Recorded recognized `escape_class` values produce class
+counts; unclassified members are never silently counted as non-escapes.
+`escape_rate` is null for an empty or incompletely classified population.
+`escape_rate_lower_bound` separately reports known production defects divided by
+the entire population. Family labels never backfill item classifications, and
+`budget_scope: "registered_families_only"` prevents policy budgets from being
+mistaken for proof about an unknown population.
+
+Registration means checks are selected, not that the defect is fixed or a
+hosted check has passed. The policy includes domain seeds for all current
+recorded components, while future disconnected recurrences fail the gate until
+a justified family is registered. Future edges within a registered lineage
+inherit protection automatically.
 
 ## Defect Evidence on PM Items
 
@@ -123,10 +187,20 @@ pnpm quality:defect-evidence
 node scripts/release/defect-evidence-gate.mjs --negative-control --json
 ```
 
-The first command must pass. The negative control must exit `1` after replacing a captured sample with a forbidden source and adding a terminal defect without evidence. Focused provider modes are available as `--boundary-only`, `--evidence-only`, and `--policy-only`.
+The first command must pass. The negative control must exit `1` after replacing a captured sample with a forbidden source and adding a terminal defect without evidence. The policy-only negative control
+adds a disconnected, unregistered recurrence pair and must also exit `1`. Focused provider modes are available as `--boundary-only`, `--evidence-only`, and `--policy-only`.
 
 `repository-defect-evidence-required` is part of the blocking `repository-static-quality` assurance composition. That makes local and CI behavior share the same provider result, assertion negative control, enforcement, and immutable verdict semantics.
 
+The mandatory `gate-registry` check also compares each recurrence family's `checks.hosted` values with concrete names derived from the repository workflows. It expands static matrix axes and applies exclusions before inclusions according to [GitHub's matrix rules](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixinclude). Renamed or removed checks produce named findings. Runtime expressions, unnamed matrix jobs, and static expansions beyond 256 combinations cannot certify a required check name. The public SDK policy parser remains provider-neutral; this workflow binding belongs to the repository gate.
+
+Assurance request schemas declare each family's required identity, triggers,
+checks, historical IDs, budgets, and negative-control input. Runtime policy
+validation additionally verifies unique family IDs and that each negative control
+actually selects its family; structural JSON Schema validation alone cannot prove
+those relationships. Risk reasons are sorted after direct and inherited matches
+are combined, using signal, value, then matched evidence as stable ordering keys.
+
 ## Recovery Producer Census
 
 `censusPmRecoveryReferenceProducers` scans complete source files for static object-literal recovery fields. It ignores type literals, destructuring patterns, labels, comments, strings, templates, and regular expressions. Aliases such as `candidate_commands`, nested `fallback_candidates[].command`, `next_best_command`, `retry_command`, and `suggested_next_steps` normalize to the same six public recovery kinds used by executable reachability verification.

package/docs/EXTENSIONS.md

@@ -91,11 +91,15 @@ Package roots declare resources in `package.json` under `pm`:
 ```
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
-`pm package init` and its compatibility spelling `pm extension init` emit the same publishable root-extension artifact (`"extensions": ["."]`): package metadata, a typed `index.ts`, a colocated `node:test` suite, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts. Both results report the canonical `package_name` and exact `invocation_command`; an already prefixed target such as `pm-my-workflow` stays `pm-my-workflow` instead of becoming `pm-pm-my-workflow`. The manifest `entry` points at `./index.ts` itself (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm package install`. The generated README shows how to author exported command/hook definitions with the SDK [define\* builders](../.agents/pm/decisions/pm-3mph.toon). `--capability` selects one of ten scaffold starters (`commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, `services`), each keeping a runnable starter command and adding the selected registration pattern plus a colocated `node:test` suite built on the matching SDK `assertRegistered*`/`runRegistered*ForTest` helpers. These are authoring selectors, not a one-to-one manifest-capability vocabulary: the `profile` starter registers a profile but declares the supported `schema` manifest capability because `api.registerProfile` is schema-governed. The option is repeatable for shell and config composition: repeating the same capability is idempotent, while combining distinct starter shapes fails with a usage error that asks the author to select one explicit scaffold capability. The full per-capability matrix (what each starter registers, which starters also declare `schema` because flag metadata is schema-governed, and why `schema`/`profile` omit `activation.commands` so their global contributions activate conservatively for every command) lives in [SDK.md — Minimal Command Extension](./SDK.md#minimal-command-extension). Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Declarative starters import `manifest.json` in their generated test and call `assertExtensionManifestMatchesBlueprint`, so capability drift fails locally before publication. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
-Package tests can pair `readPmPackageManifest(packageRoot)` with
-`assertPackageManifest(manifest, { resources: ... })` from
-`@unbrained/pm-cli/sdk` to prove aliases and resource paths without duplicating
-pm's manifest normalization logic.
+`pm package init` (and compatible `pm extension init`) creates a publishable root extension (`"extensions": ["."]`):
+
+- The artifact includes package metadata, typed `index.ts`, a colocated `node:test` suite, strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts. Results report canonical `package_name` and exact `invocation_command`; an existing `pm-` prefix is retained once.
+- The manifest points to `./index.ts`, loaded by native TypeScript stripping on Node >=22.18 ([pm-2c28](../.agents/pm/decisions/pm-2c28.toon), [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). Run `npm install` for the peer SDK and type checking before package installation; no build step is required. The README demonstrates the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon).
+- `--capability` selects `commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, or `services`. Every starter keeps a runnable command and adds matching SDK `assertRegistered*`/`runRegistered*ForTest` tests. Repeating one selection is idempotent; distinct selections fail with an actionable usage error.
+- Scaffold selectors and manifest capabilities differ: `profile` registers a profile under `schema`. The [capability matrix](SDK.md#minimal-command-extension) explains each registration, schema-governed flags, and why `schema`/`profile` omit narrow `activation.commands` so their contributions stay globally available.
+- Starter manifests declare `trusted: true`, `sandbox_profile: "strict"`, and explicit false permissions for filesystem, network, environment, and subprocess access. Declarative tests import `manifest.json` and call `assertExtensionManifestMatchesBlueprint`, detecting capability drift before publication.
+- Larger packages may use nested extension directories and declare required runtime dependencies and permissions. Validate with `pm package doctor`; its advisory `extension_schema_narrow_activation` finding recommends removing narrow activation when custom item types or fields need global availability.
+Package tests can pair `readPmPackageManifest(packageRoot)` with `assertPackageManifest(manifest, { resources: ... })` from `@unbrained/pm-cli/sdk` to prove aliases and resource paths without duplicating pm's manifest normalization logic.
 
 When no package manifest is present, `pm` discovers conventional extension directories:
 
@@ -115,7 +119,11 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root
 - `PM_GLOBAL_PATH`: global profile root
 
-Extensions are authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a minimal standalone extension has a `manifest.json` and a TypeScript `index.ts` entrypoint the loader imports directly by file URL via Node's native type stripping (Node >=22.18) — there is no compile step and no `./index.js`. Author against the SDK types with `import type { ExtensionApi }` — the type-only import is erased on load, so the `.ts` entry carries **no runtime import** of `@unbrained/pm-cli` (standalone entries are loaded outside any `node_modules`, so a runtime SDK import would fail). Type-check with `npx tsc --noEmit` after installing `typescript` and `@unbrained/pm-cli` for the type resolution.
+Extensions are authored and loaded as TypeScript ([pm-2c28](../.agents/pm/decisions/pm-2c28.toon), [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)):
+
+- A minimal standalone extension has `manifest.json` and `index.ts`. Node >=22.18 loads that entry directly with native type stripping; no compilation or `index.js` is required.
+- Use `import type { ExtensionApi }` for erased SDK types. Standalone entries outside `node_modules` need the host SDK link described below before using runtime SDK imports.
+- Install `typescript` and `@unbrained/pm-cli`, then run `npx tsc --noEmit` to check authoring types.
 
 ```json
 {
@@ -279,7 +287,7 @@ Surface tokens include command handlers/overrides, parser/preflight/services/ren
 
 Some extension surfaces are intentionally single-winner: command handlers and overrides, parser overrides, preflight overrides, and format renderers. Activation is deterministic: lower manifest `priority` values load first, omitted priority defaults to `100`, equal priorities sort by package identity/path, and the last registration wins. If multiple packages register the same single-winner surface, `pm package doctor` / `pm health` report deterministic `extension_*_collision` warnings whose suffix names the winning layer/package before the displaced layer/package. `pm package describe --json` also exposes `command_ownership`: every claimant in activation order, the effective winner, collision state, and the explicit `last_activated_wins` policy. SDK hosts can build the identical table with `buildExtensionDescribeResult` and the exported `ExtensionCommandOwnership` contracts. Renderer ownership is evaluated per command: same-format renderers with disjoint `commands` lists safely coexist, while an unscoped or overlapping claim still warns; runtime `resultDiscriminator` predicates alone cannot prove static disjointness. Tracked by [pm-6mjxgq](../.agents/pm/issues/pm-6mjxgq.toon).
 
-For definition-based commands, validation is isolated per command: a malformed definition is recorded as `extension_command_quarantined:*` with a registration trace while valid siblings continue to activate. Unknown-command recovery reports that failure without recommending reinstallation.
+For definition-based commands, a malformed definition is recorded as `extension_command_quarantined:*` with a registration trace. Activation then rolls back all registrations from that extension, preserving atomic package activation. Fix the failed definition before expecting sibling commands to load. Other valid extensions retain their registrations.
 Use the warning details to resolve the overlap:
 
 ```bash
@@ -294,12 +302,6 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
 
-```ts
-import { defineExtension } from "@unbrained/pm-cli/sdk";
-```
-
-Common APIs:
-
 - `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.
 - `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.
@@ -331,6 +333,8 @@ pm contracts --runtime-only --schema-only --json
 pm contracts --command <command> --flags-only --json
 ```
 
+`CliFlagContract.reservation_scope` tells package authors which host flags are reserved: `inherited` flags (including their aliases) cannot be redeclared by extensions; `root_only` flags belong only to the root command. The public `GLOBAL_FLAG_CONTRACTS` table from `@unbrained/pm-cli/sdk/contracts` exposes the same classification used by runtime validation. For example, an extension may define its own boolean `--explain`; root `pm --explain` keeps its host meaning. Redeclaring inherited `--json` fails validation and rolls back that package's activation. See [pm-2h8t6y](../.agents/pm/issues/pm-2h8t6y.toon).
+
 List-valued inline flags and `registerFlags` entries share one ordered
 accumulator across their long and short aliases. For a variadic positional that
 must receive values such as `-h` or `--json`, put the end-of-options separator
@@ -381,8 +385,6 @@ pm package reload --project
 pm package reload --project --watch
 ```
 
-Compatibility equivalents remain available through `pm extension ...` for existing automation.
-
 ## Upgrade Workflow
 
 `pm package upgrade` is the package-first update entrypoint:
@@ -443,7 +445,4 @@ Prefer `createExtensionTestHarness(module, { capabilities })` in package unit te
 
 ## Runnable Examples
 
-- `docs/examples/starter-extension/`
-- `docs/examples/policy-restricted-extension/`
-- `docs/examples/sdk-contract-consumer/`
-- `docs/examples/sdk-app-embedding/`
+See the [starter](examples/starter-extension/README.md), [policy-restricted](examples/policy-restricted-extension/README.md), [SDK contract consumer](examples/sdk-contract-consumer/README.md), and [SDK application](examples/sdk-app-embedding/README.md) examples.