@unbrained/pm-cli 2026.11.4 → 2026.11.5

package/docs/AGENT_OUTPUT_ENCODINGS.md

@@ -55,19 +55,19 @@ Each includes nested facts. The historical renderer is measured at commit
 Measurements are committed in `tests/fixtures/agent-encoding-baseline.json`.
 
 | Surface / rows | Previous TOON | JSON | Nested TOON | Hoisted cells | Ordinal | Selected |
-| -------------- | ------------: | ---: | ----------: | ------------: | ------: | -------: |
-| search / 1     |            83 |  110 |          70 |            86 |      88 |       73 |
-| search / 8     |           503 |  607 |         406 |           303 |     417 |      303 |
-| search / 32    |          1943 | 2311 |        1558 |          1047 |    1545 |     1047 |
-| next / 1       |            86 |  122 |          76 |            94 |      93 |       79 |
-| next / 8       |           527 |  703 |         454 |           367 |     457 |      367 |
-| next / 32      |          2039 | 2695 |        1750 |          1303 |    1705 |     1303 |
-| context / 1    |            89 |  118 |          76 |            89 |      95 |       79 |
-| context / 8    |           544 |  664 |         447 |           320 |     459 |      321 |
-| context / 32   |          2104 | 2536 |        1719 |          1112 |    1707 |     1113 |
-| get / 1        |            86 |  124 |          76 |           115 |     106 |       80 |
-| get / 8        |           408 |  551 |         279 |           311 |     400 |      264 |
-| get / 32       |          1512 | 2015 |         975 |           983 |    1408 |      840 |
+|---|---:|---:|---:|---:|---:|---:|
+| search / 1 | 83 | 110 | 70 | 86 | 88 | 73 |
+| search / 8 | 503 | 607 | 406 | 303 | 417 | 303 |
+| search / 32 | 1943 | 2311 | 1558 | 1047 | 1545 | 1047 |
+| next / 1 | 86 | 122 | 76 | 94 | 93 | 79 |
+| next / 8 | 527 | 703 | 454 | 367 | 457 | 367 |
+| next / 32 | 2039 | 2695 | 1750 | 1303 | 1705 | 1303 |
+| context / 1 | 89 | 118 | 76 | 89 | 95 | 79 |
+| context / 8 | 544 | 664 | 447 | 320 | 459 | 321 |
+| context / 32 | 2104 | 2536 | 1719 | 1112 | 1707 | 1113 |
+| get / 1 | 86 | 124 | 76 | 115 | 106 | 80 |
+| get / 8 | 408 | 551 | 279 | 311 | 400 | 264 |
+| get / 32 | 1512 | 2015 | 975 | 983 | 1408 | 840 |
 
 These are fixture measurements, not universal compression guarantees. Selected
 output combines the existing scalar presentation with a per-collection choice,
@@ -83,13 +83,13 @@ one for an extra JSON-cell decoding step or two for positional row interpretatio
 The minimum adopted score is four; it is a design criterion alongside the
 independent executable equivalence gate.
 
-| Candidate       | Readability score / 5 | Interpretation                            |
-| --------------- | --------------------: | ----------------------------------------- |
-| JSON            |                     5 | Named fields and native nested values     |
-| Nested TOON     |                     5 | Named fields and standard nested decoding |
-| Hoisted cells   |                     4 | Named columns and declared JSON cells     |
-| Ordinal         |                     3 | Column lookup plus positional nested rows |
-| Selected hybrid |                   4–5 | Expanded small rows or declared tables    |
+| Candidate | Readability score / 5 | Interpretation |
+|---|---:|---|
+| JSON | 5 | Named fields and native nested values |
+| Nested TOON | 5 | Named fields and standard nested decoding |
+| Hoisted cells | 4 | Named columns and declared JSON cells |
+| Ordinal | 3 | Column lookup plus positional nested rows |
+| Selected hybrid | 4–5 | Expanded small rows or declared tables |
 
 Ordinal arrays require an additional positional interpretation and save nothing
 on these nested fixtures, so they are not adopted. The complete brief-list

package/docs/ASSURANCE.md

@@ -33,17 +33,17 @@ The assurance SDK keeps those semantics independent from presentation. Commander
 
 Measurements support these built-in sources:
 
-| Source            | Purpose                                                                                                                                  |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `items`           | Count authoritative full item records matching status, type, tags, an exact metadata field, or a field `state` of `present`/`missing`.   |
+| Source | Purpose |
+|---|---|
+| `items` | Count authoritative full item records matching status, type, tags, an exact metadata field, or a field `state` of `present`/`missing`. |
 | `dependency_kind` | Count typed relationship edges such as `blocked_by` or `verifies`; accepted aliases and canonical spellings measure the same population. |
-| `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.                                                                  |
+| `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. |
 
 `ASSURANCE_MEASUREMENT_SOURCE_KINDS` and `ASSURANCE_GATE_TRIGGERS` are the
 public SDK constants for these closed vocabularies. Runtime validation rejects

package/docs/BOUNDED_CONTEXT_READS.md

@@ -153,7 +153,7 @@ 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 |
@@ -162,7 +162,7 @@ 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 |
@@ -175,7 +175,7 @@ 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 |

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -197,7 +197,7 @@ After installing the plugin:
 ## Compatibility
 
 | pm-cli version | Plugin version | Claude Code version |
-|---------------|----------------|---------------------|
+|---|---|---|
 | Exact same date-based version as the plugin | Exact same date-based version as pm-cli | Current supported Claude Code |
 
 The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; `pnpm version:check` also verifies the pinned runtime dependency.

package/docs/CLI_GRAMMAR.md

@@ -133,7 +133,7 @@ and cross-workspace evidence exist, published aliases remain executable.
 Tracked by [pm-m6g87m](../.agents/pm/tasks/pm-m6g87m.toon), [pm-fmy9ih](../.agents/pm/tasks/pm-fmy9ih.toon), and [pm-wfskfn](../.agents/pm/tasks/pm-wfskfn.toon).
 
 | Canonical command | Compatibility alias | Responsibility |
-| --- | --- | --- |
+|---|---|---|
 | `item copy` | `copy` | Copy one item to a new ID |
 | `workspace merge` | `merge` | Install, inspect, or run Git tracker merge drivers |
 | `item duplicates` | `duplicates` | Discover bounded duplicate clusters in core |
@@ -216,7 +216,7 @@ Tracked by [pm-npr3](../.agents/pm/tasks/pm-npr3.toon) and
 [pm-uk9dwh](../.agents/pm/tasks/pm-uk9dwh.toon).
 
 | Canonical command | Compatibility spelling | Responsibility |
-| --- | --- | --- |
+|---|---|---|
 | `workspace init` | `init` | Bootstrap storage, settings, and optional guidance |
 | `workspace config` | `config` | Read or change individual project/global settings |
 | `workspace schema` | `schema` | Define types, statuses, fields, and validation contracts |

package/docs/COMMANDS.md

@@ -51,21 +51,21 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 
 ## Command Families
 
-| Family       | Commands                                                                                                                                      | Purpose                                                                                                                                                                                                                                                |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                                       | create and inspect tracker setup                                                                                                                                                                                                                       |
-| Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `item reopen`, `append`, `close`, `release`, `close delete` | mutate item state, including terminal-work recurrence without duplicate creation                                                                                                                                                                       |
-| Bulk         | `item mutate`, `item complete`, `update many`, `close many`                                                                                   | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
-| Scheduling   | `meet`, `event`, `remind`                                                                                                                     | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
-| Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`                     | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
-| Links        | `files`, `docs`, `test`, `deps`                                                                                                               | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
-| Verification | `test`, `test-all`, `test-runs`†, `validate`, `gc`                                                                                            | run linked tests and repository checks                                                                                                                                                                                                                 |
-| History      | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats`                                              | inspect, compact, redact, re-anchor, and recover item state                                                                                                                                                                                            |
-| Schema       | `schema add/remove-*` / `rename-type` / `rename-field` / `remap-status` / `apply-preset`                                                      | manage config-driven types, statuses, and fields; losslessly migrate existing items when definitions evolve; adopt presets or infer types                                                                                                              |
-| Profiles     | `profile list` / `show` / `apply` / `lint`                                                                                                    | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
-| Calendar     | `calendar`, `cal`                                                                                                                             | project deadlines, reminders, and events                                                                                                                                                                                                               |
-| Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                                    | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
-| Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                                            | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
+| Family | Commands | Purpose |
+|---|---|---|
+| Bootstrap | `init`, `config`, `health`, `telemetry` | create and inspect tracker setup |
+| Lifecycle | `create`, `copy`, `focus`, `claim`, `update`, `item reopen`, `append`, `close`, `release`, `close delete` | mutate item state, including terminal-work recurrence without duplicate creation |
+| Bulk | `item mutate`, `item complete`, `update many`, `close many` | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint |
+| Scheduling | `meet`, `event`, `remind` | low-friction Meeting/Event/Reminder creation |
+| Planning | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize` | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization |
+| Links | `files`, `docs`, `test`, `deps` | connect items to artifacts, tests, and relationships |
+| Verification | `test`, `test-all`, `test-runs`†, `validate`, `gc` | run linked tests and repository checks |
+| History | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats` | inspect, compact, redact, re-anchor, and recover item state |
+| Schema | `schema add/remove-*` / `rename-type` / `rename-field` / `remap-status` / `apply-preset` | manage config-driven types, statuses, and fields; losslessly migrate existing items when definitions evolve; adopt presets or infer types |
+| Profiles | `profile list` / `show` / `apply` / `lint` | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
+| Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
+| Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
+| Machines | `contracts`, `help`, optional `guide`/`completion` | command contracts plus optional guide-shell docs routing and shell helpers |
 
 `†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm package install linked-test-adapters --project`).
 
@@ -968,8 +968,12 @@ Starting work respects declared blockers
 in_progress`, `pm claim <id> --start`, `pm claim --next --start` and the
 `start-task` action refuse with `start_blocked_by_open_dependency` (exit 4)
 when the item moves into the start status while a `blocked_by` target is still
-open. An item already in that status is not rechecked, so `claim --start` on it
-succeeds. The check runs before any write: the
+open. `pm claim --next --start` skips a ranked candidate refused this way (its
+blocker opened after ranking, and nothing is written to it), claims the next
+eligible candidate, and lists the skipped ids in `start_refused`. When the walk
+is exhausted, the `no_available_next_item` refusal (or the `--if-available`
+empty result) carries them too. An item already in that status is not
+rechecked, so `claim --start` on it succeeds. The check runs before any write: the
 explicit `claim <id> --start` judges it under the claim's item lock, and its
 status update judges again under its own lock. When the first check refuses,
 nothing is written. When a blocker opens between the two writes, the start
@@ -1031,7 +1035,24 @@ carrying `error_code`, `expected_revision`, `current_revision` and
 `details.changes_since`. When `close` auto-unblocks a guarded dependent whose revision
 moved, the close stays committed and the command refuses with that dependent's
 `item_revision_conflict` once the fan-out finishes. `side_effects` names every
-write that committed first: the close and each dependent already unblocked. `close-many` reports such a row as `closed` (`update-many` closing
+write that committed first: the close and each dependent already unblocked. Do
+not retry the close; it is already terminal. `required` and `nextSteps` name
+only the remaining step for each refused guarded dependent
+(`details.pending_unblock`): re-read it, confirm every blocker it declares is
+resolved, then run the scoped unblock `nextSteps` lists (`pm update <dependent>
+--status <open-status> --unset blocked_by --unset blocked_reason --expect-hash
+<dependent>=<item_hash>`, carrying the configured open status and tracker
+scope). `--unset blocked_by` removes every `blocked_by` edge, including one a
+concurrent change added, so skipping the check can reopen a still-blocked item.
+Dependents whose unblock failed for another reason are in
+`details.auto_unblock_failed` with that reason; fix the cause first. Each list
+names at most 10 ids and counts the rest in `*_omitted`, keeping the details
+within the error-details size limit. When ids were omitted, or the steps exceed
+the 20-step cap (ten conflicts plus one other failure make 21), the last step
+lists every item in a blocked-role status (`pm list --status <blocked-statuses>
+--fields id,title,blocked_by,dependencies`, over the statuses the fan-out drew
+from), so a dependent whose step was cut is still found; it returns 200 rows per
+page, so follow `--after <next_cursor>` while `has_more: true`. `close-many` reports such a row as `closed` (`update-many` closing
 through `--status`, as `updated`), with the dependent's conflict under
 `dependent_revision_conflict`. A guarded `restore` refuses to recover
 over a live file that cannot be read as a document; an unguarded restore still
@@ -1578,23 +1599,23 @@ pm plan show <plan-id> --fields id,title,steps_summary
 
 Subcommand cheatsheet:
 
-| Subcommand        | Purpose                                                                                      |
-| ----------------- | -------------------------------------------------------------------------------------------- |
-| `create`          | Create a Plan item with scope, harness, parent, related, blocked-by, and optional auto-claim |
-| `show`            | Progressive-disclosure read (brief / standard / deep) with current step + next-action hints  |
-| `add-step`        | Append a step with title/body/owner/status/dependencies/files/tests/docs                     |
-| `update-step`     | Patch one step (title, body, status, evidence, owner, blocked reason)                        |
-| `complete-step`   | Shortcut for setting a step to `completed` with evidence                                     |
-| `block-step`      | Shortcut for setting a step to `blocked` with required `--step-blocked-reason`               |
-| `reorder-step`    | Move a step to a new 1-based order                                                           |
-| `remove-step`     | Drop a step and renumber remaining steps                                                     |
-| `link` / `unlink` | Add or remove `linked_items` on a step (with optional `--promote-to-item-dep`)               |
-| `decision`        | Append a decision log entry (decision/rationale/evidence)                                    |
-| `discovery`       | Append a discovery log entry                                                                 |
-| `validation`      | Append a validation check (text/command/expected)                                            |
-| `resume`          | Replace the resume-context summary for stateless agents                                      |
-| `approve`         | Move `plan_mode` to `approved` (default) or any other mode via `--mode`                      |
-| `materialize`     | Create real pm items (default `Task`) from selected steps with bidirectional links           |
+| Subcommand | Purpose |
+|---|---|
+| `create` | Create a Plan item with scope, harness, parent, related, blocked-by, and optional auto-claim |
+| `show` | Progressive-disclosure read (brief / standard / deep) with current step + next-action hints |
+| `add-step` | Append a step with title/body/owner/status/dependencies/files/tests/docs |
+| `update-step` | Patch one step (title, body, status, evidence, owner, blocked reason) |
+| `complete-step` | Shortcut for setting a step to `completed` with evidence |
+| `block-step` | Shortcut for setting a step to `blocked` with required `--step-blocked-reason` |
+| `reorder-step` | Move a step to a new 1-based order |
+| `remove-step` | Drop a step and renumber remaining steps |
+| `link` / `unlink` | Add or remove `linked_items` on a step (with optional `--promote-to-item-dep`) |
+| `decision` | Append a decision log entry (decision/rationale/evidence) |
+| `discovery` | Append a discovery log entry |
+| `validation` | Append a validation check (text/command/expected) |
+| `resume` | Replace the resume-context summary for stateless agents |
+| `approve` | Move `plan_mode` to `approved` (default) or any other mode via `--mode` |
+| `materialize` | Create real pm items (default `Task`) from selected steps with bidirectional links |
 
 Invariants:
 

package/docs/COMMAND_NAMESPACES.md

@@ -9,7 +9,7 @@ spellings remain executable compatibility aliases with the same arguments,
 results, exit codes, and SDK behavior.
 
 | Native invocation | Compatibility spelling | Purpose |
-| --- | --- | --- |
+|---|---|---|
 | `pm context next` | `pm next` | Select ready work and explain blockers |
 | `pm context focus` | `pm focus` | Read, set, or clear the focused item |
 | `pm ops stats` | `pm stats` | Inspect tracker statistics |

package/docs/CONFIGURATION.md

@@ -37,7 +37,7 @@ it to the right typed flag based on the key (so `--policy`/`--format`/`--criteri
 remain optional for single values):
 
 ```bash
-pm config set telemetry-tracking off          # off|on|true|false map to disabled|enabled
+pm config set telemetry-tracking off          # off|on|true|false; global profile
 pm config set item-format toon                # same as --format toon
 pm config set governance-preset strict        # same as --policy strict
 pm config set definition-of-done "Tests pass" # same as --criterion "Tests pass"
@@ -80,35 +80,35 @@ If the existing `settings.json` is valid JSON but fails schema validation (for e
 
 ## Common Settings
 
-| Setting                                    | Purpose                                                                                                                                                                                               |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id_prefix`                                | generated item ID prefix, default `pm-`                                                                                                                                                               |
-| `ids.token_length`                         | random base36 token length for newly minted item ids (4-12, default `4`); raise it to shrink cross-branch id collision odds in concurrent multi-agent workflows (see [Merge Safety](MERGE_SAFETY.md)) |
-| `author_default`                           | configured mutation author before automatic harness detection                                                                                                                                         |
-| `mutation_guard.require_attributed_author` | reject mutations whose effective author remains `unknown` (default `false`)                                                                                                                           |
-| `mutation_guard.secret_guard`              | credential-shaped content policy: `off`, `advise`, or `block` (default `advise`)                                                                                                                      |
-| `mutation_guard.stale_in_progress_hours`   | age threshold for unclaimed in-progress work surfaced by `pm health` (integer >= 1, default `72`)                                                                                                     |
-| `item_format`                              | item storage format (`toon` writes; legacy markdown is read/migrate only)                                                                                                                             |
-| `output.default_format`                    | default renderer, usually `toon`                                                                                                                                                                      |
-| `locks.ttl_seconds`                        | stale lock threshold                                                                                                                                                                                  |
-| `locks.wait_ms`                            | wait budget before a contended lock returns `lock_conflict`; item-store mutations, restore and the hierarchy lock restart it on each owner handoff (120 s cap), other locks use it as a fixed total (default `3000`; `0` fails fast) |
-| `history.missing_stream`                   | `auto_create` or `strict_error`                                                                                                                                                                       |
-| `history.compact_policy.enabled`           | enable the compaction advisory: `pm health` warns on over-threshold streams (default `false`); when disabled, `max_entries`/`trigger` are inert                                                       |
-| `history.compact_policy.max_entries`       | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`)                                  |
-| `history.compact_policy.trigger`           | policy intent when enabled: `health_warn` (advisory only) or `auto` (scheduled sweeps expected)                                                                                                       |
-| `testing.record_results_to_items`          | persist bounded linked-test summaries                                                                                                                                                                 |
-| `testing.allow_untrusted_linked_tests`     | permit the explicit `pm test --allow-untrusted-linked-tests` one-run override (default `false`; does not trust or execute commands by itself)                                                         |
-| `validation.sprint_release_format`         | `warn` or `strict_error`                                                                                                                                                                              |
-| `validation.parent_reference`              | `warn` or `strict_error` (`strict_error` is the built-in default; `pm create --allow-missing-parent` is the explicit escape hatch)                                                                    |
-| `item_types.definitions[]`                 | custom item types and type options                                                                                                                                                                    |
-| `governance.create_default_type`           | default `--type` used by `pm create "title"` when `--type` is omitted (defaults to `Task`); must resolve to a known item type                                                                         |
-| `governance.workflow_enforcement`          | per-type transition enforcement mode for `pm update --status` (`off` default, `warn`, or `strict`)                                                                                                    |
-| `governance.start_blocker_enforcement`     | starting an item (`update --status in_progress`, `claim --start`) while a declared `blocked_by` target is open: `strict` (default; refuse unless `--force`), `warn`, or `off`                         |
-| `governance.duplicate_detection_mode`      | create/copy similarity policy: `off`, `advisory`, or `strict`; the minimal preset uses `off`, while the default and strict presets use `strict`                                                       |
-| `governance.duplicate_detection_threshold` | inclusive likely-duplicate score from `0` through `1` (default `0.8`)                                                                                                                                 |
-| `governance.duplicate_detection_limit`     | maximum matches attached to a create/copy advisory from `0` through `20` (default `3`)                                                                                                                |
-| `schema.type_workflows[]`                  | per-type allowed status transitions (see Per-Type Workflows below)                                                                                                                                    |
-| `search.*`                                 | search mode, scoring, providers, embedding timeout, and vector settings                                                                                                                               |
+| Setting | Purpose |
+|---|---|
+| `id_prefix` | generated item ID prefix, default `pm-` |
+| `ids.token_length` | random base36 token length for newly minted item ids (4-12, default `4`); raise it to shrink cross-branch id collision odds in concurrent multi-agent workflows (see [Merge Safety](MERGE_SAFETY.md)) |
+| `author_default` | configured mutation author before automatic harness detection |
+| `mutation_guard.require_attributed_author` | reject mutations whose effective author remains `unknown` (default `false`) |
+| `mutation_guard.secret_guard` | credential-shaped content policy: `off`, `advise`, or `block` (default `advise`) |
+| `mutation_guard.stale_in_progress_hours` | age threshold for unclaimed in-progress work surfaced by `pm health` (integer >= 1, default `72`) |
+| `item_format` | item storage format (`toon` writes; legacy markdown is read/migrate only) |
+| `output.default_format` | default renderer, usually `toon` |
+| `locks.ttl_seconds` | stale lock threshold |
+| `locks.wait_ms` | wait budget before a contended lock returns `lock_conflict`; item-store mutations, restore and the hierarchy lock restart it on each owner handoff (120 s cap), other locks use it as a fixed total (default `3000`; `0` fails fast) |
+| `history.missing_stream` | `auto_create` or `strict_error` |
+| `history.compact_policy.enabled` | enable the compaction advisory: `pm health` warns on over-threshold streams (default `false`); when disabled, `max_entries`/`trigger` are inert |
+| `history.compact_policy.max_entries` | when the policy is enabled, the entry count above which a stream is flagged by `pm health` and the default `pm history-compact --all-over` threshold (default `500`) |
+| `history.compact_policy.trigger` | policy intent when enabled: `health_warn` (advisory only) or `auto` (scheduled sweeps expected) |
+| `testing.record_results_to_items` | persist bounded linked-test summaries |
+| `testing.allow_untrusted_linked_tests` | permit the explicit `pm test --allow-untrusted-linked-tests` one-run override (default `false`; does not trust or execute commands by itself) |
+| `validation.sprint_release_format` | `warn` or `strict_error` |
+| `validation.parent_reference` | `warn` or `strict_error` (`strict_error` is the built-in default; `pm create --allow-missing-parent` is the explicit escape hatch) |
+| `item_types.definitions[]` | custom item types and type options |
+| `governance.create_default_type` | default `--type` used by `pm create "title"` when `--type` is omitted (defaults to `Task`); must resolve to a known item type |
+| `governance.workflow_enforcement` | per-type transition enforcement mode for `pm update --status` (`off` default, `warn`, or `strict`) |
+| `governance.start_blocker_enforcement` | starting an item (`update --status in_progress`, `claim --start`, `claim --next --start`, `start-task`) while a declared `blocked_by` target is open: `strict` (default; refuse unless `--force`), `warn`, or `off`; `claim --next --start` skips a refused candidate and claims the next eligible one |
+| `governance.duplicate_detection_mode` | create/copy similarity policy: `off`, `advisory`, or `strict`; the minimal preset uses `off`, while the default and strict presets use `strict` |
+| `governance.duplicate_detection_threshold` | inclusive likely-duplicate score from `0` through `1` (default `0.8`) |
+| `governance.duplicate_detection_limit` | maximum matches attached to a create/copy advisory from `0` through `20` (default `3`) |
+| `schema.type_workflows[]` | per-type allowed status transitions (see Per-Type Workflows below) |
+| `search.*` | search mode, scoring, providers, embedding timeout, and vector settings |
 
 Lock recovery is tracked by
 [pm-02z97f](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-02z97f.toon)
@@ -219,15 +219,15 @@ underscore aliases remain accepted for compatibility.
 
 ## Environment Variables
 
-| Variable                          | Use                                                                                                                      |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `PM_AUTHOR`                       | optional explicit session-wide mutation author override                                                                  |
-| `PM_PATH`                         | override project tracker root for tests or sandboxes                                                                     |
-| `PM_GLOBAL_PATH`                  | override global profile root for tests or sandboxes                                                                      |
-| `PM_LOCK_WAIT_MS`                 | per-process override for the `locks.wait_ms` budget (a no-progress window only where that lock uses the progress policy); non-negative integer milliseconds, with `0` restoring fail-fast lock conflicts |
-| `PM_OLLAMA_MODEL`                 | choose default Ollama embedding model                                                                                    |
-| `PM_DISABLE_OLLAMA_AUTO_DEFAULTS` | disable implicit Ollama search defaults                                                                                  |
-| `PM_CONTEXT_USAGE_DISABLED`       | set to `1` to disable the derived context/next usage-feedback ledger with zero filesystem reads or writes                |
+| Variable | Use |
+|---|---|
+| `PM_AUTHOR` | optional explicit session-wide mutation author override |
+| `PM_PATH` | override project tracker root for tests or sandboxes |
+| `PM_GLOBAL_PATH` | override global profile root for tests or sandboxes |
+| `PM_LOCK_WAIT_MS` | per-process override for the `locks.wait_ms` budget (a no-progress window only where that lock uses the progress policy); non-negative integer milliseconds, with `0` restoring fail-fast lock conflicts |
+| `PM_OLLAMA_MODEL` | choose default Ollama embedding model |
+| `PM_DISABLE_OLLAMA_AUTO_DEFAULTS` | disable implicit Ollama search defaults |
+| `PM_CONTEXT_USAGE_DISABLED` | set to `1` to disable the derived context/next usage-feedback ledger with zero filesystem reads or writes |
 
 For command-level tracker targeting, prefer `--pm-path <tracker-root>`. The old
 `--path` flag is still accepted, but it means the pm tracker storage directory
@@ -264,23 +264,31 @@ Tests should set both `PM_PATH` and `PM_GLOBAL_PATH` to temporary directories. T
 
 ### Telemetry environment variables
 
-Telemetry is enabled by default. Use `pm config set telemetry-tracking off` to opt out persistently (see [Common Settings](#common-settings)). When enabled, these environment variables tune runtime behaviour. All boolean knobs accept `1`, `true`, `yes`, or `on` (case-insensitive); any other value leaves the knob off.
+Telemetry is enabled by default. Use `pm config set telemetry-tracking off` to opt out persistently (see [Common Settings](#common-settings)). Consent and the event endpoint live only in the global profile:
 
-| Variable                             | Values                                        | Use                                                                                                                                             |
-| ------------------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PM_TELEMETRY_DISABLED`              | boolean                                       | Hard-disable all telemetry for this process, ignoring settings.                                                                                 |
+- A scope-less `telemetry-tracking` call targets the global profile.
+- Project-scope `get` and `set` refuse. Project `list` and `export` omit the key.
+- `pm init` asks only while no choice is recorded in the global profile. It keeps a choice another process records while its prompt is open. It reports the global value and writes no project `telemetry` block.
+- An older project `telemetry` block is ignored.
+
+When enabled, these environment variables tune runtime behaviour. All boolean knobs accept `1`, `true`, `yes`, or `on` (case-insensitive); any other value leaves the knob off.
+
+| Variable | Values | Use |
+|---|---|---|
+| `PM_TELEMETRY_DISABLED` | boolean | Hard-disable all telemetry for this process, ignoring settings. |
 | `DO_NOT_TRACK` | boolean | Hard-disable event capture, identity creation, flush workers, endpoint probes, and Sentry, regardless of persisted preferences. |
 | `PM_TELEMETRY_SEND_TEST_EVENTS` | boolean | Explicitly allow inferred test events. Hard opt-outs still take precedence. |
 | `PM_TELEMETRY_READ_SAMPLE_RATE` | number greater than `0` and at most `1` | Override automatic successful-read sampling; `1`, empty, or invalid values retain every invocation. Omit for automatic frequency bounding. |
-| `PM_NO_TELEMETRY`                    | boolean                                       | Alias for `PM_TELEMETRY_DISABLED` (honoured by the same checks).                                                                                |
-| `PM_TELEMETRY_OTEL_DISABLED`         | boolean                                       | Disable only OTLP trace-span export; the event queue still flushes.                                                                             |
-| `PM_TELEMETRY_INLINE_FLUSH`          | boolean                                       | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
-| `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Unrecognized nonempty values use inferred context with `source_context_source=env_override_rejected`; the raw value is never emitted.                            |
-| `PM_TELEMETRY_HTTP_TIMEOUT_MS`       | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
-| `PM_TELEMETRY_INGEST_KEY`            | string                                        | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged.                                                                         |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL                                           | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint.                                                           |
-| `OTEL_EXPORTER_OTLP_ENDPOINT`        | URL                                           | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`.                                                                   |
-| `OTEL_SERVICE_NAME`                  | string                                        | `service.name` attribute on exported spans (defaults to `pm-cli`).                                                                              |
+| `PM_NO_TELEMETRY` | boolean | Alias for `PM_TELEMETRY_DISABLED` (honoured by the same checks). |
+| `PM_TELEMETRY_OTEL_DISABLED` | boolean | Disable only OTLP trace-span export; the event queue still flushes. |
+| `PM_TELEMETRY_INLINE_FLUSH` | boolean | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
+| `PM_TELEMETRY_SOURCE_CONTEXT` | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Unrecognized nonempty values use inferred context with `source_context_source=env_override_rejected`; the raw value is never emitted. |
+| `PM_TELEMETRY_HTTP_TIMEOUT_MS` | integer milliseconds | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL). |
+| `PM_TELEMETRY_INGEST_KEY` | string | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged. |
+| `PM_TELEMETRY_ENDPOINT` | http(s) URL | Deliver events to this collector instead of the configured endpoint. Events captured under it go to a queue and state file of their own that only a process with the same value reads or reports; a later flush removes them after a day idle. `pm telemetry clear` removes them too, but it also revokes consent and deletes every telemetry queue and state file of the profile. An empty value uses the configured endpoint; any other value that is not an http(s) URL disables delivery. URL credentials are sent as Basic auth, by `pm health --check-telemetry` too. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | URL | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`. |
+| `OTEL_SERVICE_NAME` | string | `service.name` attribute on exported spans (defaults to `pm-cli`). |
 
 Unrecognized source-context overrides produce one bounded warning per process on
 stderr, naming the accepted values without echoing the rejected input. JSON
@@ -326,9 +334,12 @@ Interaction rules:
 
 Test environments inferred from `VITEST`, `VITEST_WORKER_ID`, `NODE_TEST_CONTEXT`
 (native `node --test` children), or `NODE_ENV=test` suppress telemetry and Sentry
-before identity creation. A valid explicit `PM_TELEMETRY_SOURCE_CONTEXT` or
-`PM_TELEMETRY_SEND_TEST_EVENTS=1` permits intentional test delivery. Point such
-tests at a local collector. Inferred tests use inline telemetry flushing even
+before identity creation. A valid explicit `PM_TELEMETRY_SOURCE_CONTEXT`,
+including `test`, or `PM_TELEMETRY_SEND_TEST_EVENTS=1` permits intentional test
+delivery, so a test that only wants the label must also set
+`PM_TELEMETRY_DISABLED=1`. Point such tests at a local collector: set
+`PM_TELEMETRY_ENDPOINT` for events, `SENTRY_DSN` for errors, and
+`OTEL_EXPORTER_OTLP_*` for spans. Inferred tests use inline telemetry flushing even
 after an opt in, so CLI delivery settles before process exit and disposable-root
 cleanup. SDK telemetry completion also awaits inline delivery before returning.
 Neither setting overrides a hard opt-out. `pm telemetry status` exposes effective `enabled`, persisted
@@ -361,12 +372,12 @@ Tracing and privacy delivery: [pm-58yzil](../.agents/pm/features/pm-58yzil.toon)
 
 Crash and error diagnostics are reported to Sentry only when telemetry is enabled and the process is not opted out. These environment variables tune the Sentry client.
 
-| Variable                    | Values         | Use                                                                                                                                                                                                                         |
-| --------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PM_SENTRY_DISABLED`        | boolean        | Disable Sentry error reporting for this process (the Sentry SDK is not even imported). `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` also disable it.                                                                         |
-| `SENTRY_DSN`                | URL            | Override the destination DSN. Defaults to the bundled pm-cli project DSN.                                                                                                                                                   |
-| `SENTRY_ENVIRONMENT`        | string         | Override the reported environment tag. Defaults to `test` under Vitest, `ci` when `CI` is set, otherwise `production`.                                                                                                      |
-| `PM_SENTRY_TRACE_COMMANDS`  | boolean        | Explicitly initialize Sentry for successful commands. Defaults to off, preserving lazy startup. All consent opt-outs and test isolation still apply; a zero trace sample rate avoids initialization. |
+| Variable | Values | Use |
+|---|---|---|
+| `PM_SENTRY_DISABLED` | boolean | Disable Sentry error reporting for this process (the Sentry SDK is not even imported). `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` also disable it. |
+| `SENTRY_DSN` | URL | Override the destination DSN. Defaults to the bundled pm-cli project DSN. |
+| `SENTRY_ENVIRONMENT` | string | Override the reported environment tag. Defaults to `test` under Vitest, `ci` when `CI` is set, otherwise `production`. |
+| `PM_SENTRY_TRACE_COMMANDS` | boolean | Explicitly initialize Sentry for successful commands. Defaults to off, preserving lazy startup. All consent opt-outs and test isolation still apply; a zero trace sample rate avoids initialization. |
 | `SENTRY_TRACES_SAMPLE_RATE` | number `0`–`1` | Fraction of command spans sampled for performance tracing. Defaults to `0.2` (20%). Set to `1` for full-trace performance debugging or `0` to disable tracing. Non-numeric or out-of-range values fall back to the default. |
 
 > Sentry is hard-disabled under Vitest (`VITEST` / `VITEST_WORKER_ID`), so these knobs are no-ops inside the test suite.
@@ -629,21 +640,21 @@ When query expansion or rerank providers fail, `pm search` degrades gracefully a
 
 `search.default_mode` decides the mode a bare `pm search` runs in (`--mode` always wins):
 
-| Value                | Behavior                                                                                                                                                          |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auto`               | default; `hybrid` when `search.provider` names the active embedding provider and a vector store or extension adapter resolves (or an extension search provider is active), `keyword` otherwise |
-| `keyword`            | pin exact-token ranking for every bare search                                                                                                                     |
-| `semantic`, `hybrid` | pin the semantic path; an unreachable provider still degrades to keyword hits with a `search_semantic_fallback` warning                                            |
+| Value | Behavior |
+|---|---|
+| `auto` | default; `hybrid` when `search.provider` names the active embedding provider and a vector store or extension adapter resolves (or an extension search provider is active), `keyword` otherwise |
+| `keyword` | pin exact-token ranking for every bare search |
+| `semantic`, `hybrid` | pin the semantic path; an unreachable provider still degrades to keyword hits with a `search_semantic_fallback` warning |
 
 Every search result reports `mode_source` (`explicit`, `settings`, or `auto`) beside the effective `mode`.
 
 Mutation commands invalidate keyword search caches immediately. Semantic vector refresh is controlled by `search.mutation_refresh_policy`:
 
-| Policy                | Behavior                                                                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `semantic_configured` | default; refresh vectors during mutations only when semantic provider/store settings are explicitly configured      |
-| `cache_only`          | fastest writes; invalidate keyword caches and leave vector refresh to `pm reindex` or `pm health --refresh-vectors` |
-| `semantic_auto`       | also apply implicit local Ollama/LanceDB defaults during mutations                                                  |
+| Policy | Behavior |
+|---|---|
+| `semantic_configured` | default; refresh vectors during mutations only when semantic provider/store settings are explicitly configured |
+| `cache_only` | fastest writes; invalidate keyword caches and leave vector refresh to `pm reindex` or `pm health --refresh-vectors` |
+| `semantic_auto` | also apply implicit local Ollama/LanceDB defaults during mutations |
 
 Useful commands:
 

package/docs/CONTEXT_ALGORITHM_PORTFOLIO.md

@@ -28,7 +28,7 @@ Where two descriptions express one experiment, both slugs resolve to its owner.
 Existing acceptance owners retain their original delivery boundary.
 
 | Stable slug | Historical ordinal | Source note (UTC) | Canonical owner | Disposition |
-| --- | --- | --- | --- | --- |
+|---|---|---|---|---|
 | `act-r-activation` | 1 | 2026-07-07T15:12:12.161Z | [pm-fr9ok0](../.agents/pm/tasks/pm-fr9ok0.toon) | Proposed experiment |
 | `typed-spreading-activation` | 2 | 2026-07-07T15:12:12.161Z | [pm-fdb8e8](../.agents/pm/tasks/pm-fdb8e8.toon) | Proposed experiment |
 | `learned-linear-signal-weights` | 3 | 2026-07-07T15:12:12.161Z | [pm-ex5p2u](../.agents/pm/tasks/pm-ex5p2u.toon) | Proposed experiment |
@@ -112,7 +112,7 @@ The 18 candidate compositions from pm-vvib retain the architecture decision gate
 Individual experiment drafts record the ideas without accepting that decision.
 
 | Candidate | Composition | Canonical owner |
-| --- | --- | --- |
+|---|---|---|
 | 1 | Prospective memory | [pm-0uvib0](../.agents/pm/tasks/pm-0uvib0.toon) |
 | 2 | Metacognitive revalidation | [pm-ur2t9o](../.agents/pm/tasks/pm-ur2t9o.toon) |
 | 3 | Interference and belief revision | [pm-xfta80](../.agents/pm/tasks/pm-xfta80.toon) |

package/docs/CONTEXT_INTEGRITY_CONTRACTS.md

@@ -53,11 +53,11 @@ History writers using item-hash epoch 2 always emit `item_hash_version: 2`. An e
 
 Repair keeps implicit legacy streams implicit and byte-stable when no drift exists. Unsupported explicit epochs still fail with a typed `unsupported_item_hash_version` diagnostic instead of being rewritten.
 
-| Writer/runtime range                     | Item-hash output | Read contract                                                                                                                  |
-| ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| Legacy writers before an explicit marker | implicit epoch 1 | Modern readers retain legacy canonicalization candidates.                                                                      |
-| Observed 2026.8.24 through 2026.8.28     | explicit epoch 2 | Modern readers accept both field-frozen and expanded epoch-2 forms without mixing forms inside one entry.                      |
-| 2026.8.31 and newer                      | explicit epoch 3 | Exact pins and bounded ranges that cannot select an epoch-3 reader cause current runtimes to reject the write before mutation. |
+| Writer/runtime range | Item-hash output | Read contract |
+|---|---|---|
+| Legacy writers before an explicit marker | implicit epoch 1 | Modern readers retain legacy canonicalization candidates. |
+| Observed 2026.8.24 through 2026.8.28 | explicit epoch 2 | Modern readers accept both field-frozen and expanded epoch-2 forms without mixing forms inside one entry. |
+| 2026.8.31 and newer | explicit epoch 3 | Exact pins and bounded ranges that cannot select an epoch-3 reader cause current runtimes to reject the write before mutation. |
 
 The table records confirmed release boundaries rather than inventing an exact
 first release for legacy epoch 1 or epoch 2. The SDK exports

package/docs/CORPUS_SHAPES.md

@@ -46,7 +46,7 @@ identifier is `https://schema.unbrained.dev/pm/corpus-shape/v1`.
 ## Built-in populations
 
 | Shape | Purpose |
-|-------|---------|
+|---|---|
 | `scratch` | Seconds-old, shallow project with minimal history |
 | `representative` | Medium-lived project with rich evidence and typed lineage |
 | `deep-graph` | Deep relationship graph with deterministic cycles |

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -4,12 +4,12 @@ Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agent
 
 Dependency rows have one canonical stored spelling per relationship meaning. Command inputs remain compatibility-friendly: hyphens normalize to underscores and the aliases below are accepted, but `pm create` and `pm update` persist the canonical kind. Existing historical rows are never rewritten implicitly.
 
-| Canonical kind | Accepted legacy aliases                |
-| -------------- | -------------------------------------- |
-| `blocked_by`   | `depends_on`, `depends-on`             |
-| `related`      | `related_to`, `related-to`             |
-| `parent`       | `child_of`, `child-of`, `epic`         |
-| `child`        | `parent_child`, `parent-child`, `task` |
+| Canonical kind | Accepted legacy aliases |
+|---|---|
+| `blocked_by` | `depends_on`, `depends-on` |
+| `related` | `related_to`, `related-to` |
+| `parent` | `child_of`, `child-of`, `epic` |
+| `child` | `parent_child`, `parent-child`, `task` |
 
 `epic` and `task` are compatibility aliases, not item types embedded in the relationship ontology. New integrations should use `parent` or `child` and express the work classification through the item `type` field.