@unbrained/pm-cli 2026.11.3 → 2026.11.5

package/docs/AGENT_GUIDE.md

@@ -124,54 +124,54 @@ tests compare complete history bytes while the unrelated tracker's claims change
 
 ## Token-Minimal Retrieval
 
-| Need                                 | Command                                                                                                                                                    |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The single next action + why         | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
-| Next ready work in one epic          | `pm next --parent <id>`                                                                                                                                    |
-| Canonical cold-start orientation     | `pm context --for orient` (1,055 estimated tokens on the fixed 101-item replay corpus)                                                          |
-| Next work and agenda                 | `pm context --limit 10`                                                                                                                                    |
-| Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap)                                                                                          |
-| Status of one epic/subtree           | `pm context --parent <id> --depth deep`                                                                                                                    |
-| Relevant items                       | `pm search "<keywords>" --limit 10` (keyword hits are score-ranked; keyword mode defaults to 50 results, `result.total` reports the full pre-limit count)  |
-| Require every query token            | `pm search "<keywords>" --match-mode and` (hard-filter; `exact` = contiguous phrase; default `or` adds an all-terms ranking bonus)                         |
-| Just the match count                 | `pm search "<keywords>" --count` (no hit rows; `count`/`total` carry the matched total)                                                                    |
-| Per-query score threshold            | `pm search "<keywords>" --min-score 5` (overrides settings `search.score_threshold` for this query)                                                        |
-| Every matched row (no cap)           | `pm list --all --no-truncate --brief` (`result.total` reports the full count when a `--limit`/`--offset` truncates)                                        |
-| Item bodies in bulk (one call)       | `pm list --status open --json --include-body` (avoids one `pm get` per item)                                                                               |
-| Open work only                       | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos)                                                                 |
-| Scope search like list               | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity)                                                        |
-| Items changed since last window      | `pm list --all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work)                                                                    |
-| Open items changed today             | `pm list --status open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`)                                              |
-| Items changed recently               | `pm list --all --recent --brief` (last seven days; mutually exclusive with `--updated-after`)                                                              |
-| Single item                          | `pm get <id>`                                                                                                                                              |
-| Full machine payload                 | `pm get <id> --full --json`                                                                                                                                |
-| Command flags                        | `pm <command> --help --json`                                                                                                                               |
-| Command intent map                   | `pm contracts --summary --json` (one command plus terse intent per row; use before command-scoped contracts)                                               |
-| Low-noise machine contracts          | `pm contracts --command <command> --flags-only --json`                                                                                                     |
-| Semantic index refresh               | `pm reindex --mode semantic --progress` (stale-first by default; add `--full` to force full rebuild; requires the `search-advanced` package)               |
-| Timeline                             | `pm activity --id <id> --limit 20`                                                                                                                         |
-| Audited history redaction            | `pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run`                                                                         |
-| Audited history re-anchor            | `pm history-repair <id> --dry-run` (clears drift flagged by `pm health`/`pm validate`)                                                                     |
-| Register custom item type            | `pm schema add-type <Name> --description "<text>" --default-status open` (then `pm create <Name> "..."`)                                                   |
-| Remove custom item type              | `pm schema remove-type <Name>` (warns if items still use it; built-ins refused)                                                                            |
-| Register custom status               | `pm schema add-status <id> --role <active\|terminal\|...> --alias <name> --order <n>`                                                                      |
-| Remove custom status                 | `pm schema remove-status <id>` (warns if items use it; built-in statuses refused)                                                                          |
-| Agent plan create                    | `pm plan create --title "<scope>" --harness claude-code --scope "<short>" --claim`                                                                         |
-| Agent plan create with steps         | `pm plan create --title "<scope>" --step "<step 1>" --step "<step 2>" --step "<step 3>"` (repeated `--step` seeds ordered steps)                           |
-| Agent plan step update               | `pm plan update-step <plan-id> plan-step-001 --step-status in_progress --step-evidence "<short>"`                                                          |
-| Agent plan read                      | `pm plan show <plan-id> --depth brief` (or `--fields id,title,steps_summary`)                                                                              |
-| Materialize plan steps               | `pm plan materialize <plan-id> --steps plan-step-002 --materialize-type Task`                                                                              |
-| Dependencies                         | `pm deps <id> --format tree`                                                                                                                               |
-| Graph queries                        | `pm graph successors <id> --limit 20` (also `ancestors`, `paths`, `impact`, `analyze`, `audit`, `communities`, `redundancy`, `dominators`, `plan`)         |
-| Bulk update by id allowlist          | `pm update-many --ids pm-a,pm-b --priority 1 --dry-run` (preview, then drop `--dry-run`)                                                                   |
-| Audited bulk close (sprint closeout) | `pm close-many --filter-sprint <s> --reason "<text>" --dry-run` (full `pm close` semantics per item; `--rollback <id>` to undo)                            |
-| Local docs routing                   | `pm install guide-shell --project`, then `pm guide <topic>`                                                                                                |
-| Compact mutation echo                | `pm --no-changed-fields create "..."` (drops the redundant `changed_fields` array, keeps `changed_field_count`)                                            |
-| Minimal mutation echo                | `pm --id-only create "..."` (prints only id and status for single-item mutations)                                                                          |
-| Duplicate close                      | `pm close <duplicate> --duplicate-of <canonical>` (or `-d <canonical>`)                                                                                    |
-| Long body from a file                | `pm create <Type> "<title>" --body-file ./spec.md` (also on `pm update`; mutually exclusive with `--body`)                                                 |
-| Close with short flags               | `pm close <id> -r "<reason>"` / `-m "<history msg>"` / `-d <canonical>`                                                                                    |
-| Close via resolution only            | `pm close <id> --resolution "<summary>"` (used as the close reason when one is required)                                                                   |
+| Need | Command |
+|---|---|
+| The single next action + why | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
+| Next ready work in one epic | `pm next --parent <id>` |
+| Canonical cold-start orientation | `pm context --for orient` (1,055 estimated tokens on the fixed 101-item replay corpus) |
+| Next work and agenda | `pm context --limit 10` |
+| Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap) |
+| Status of one epic/subtree | `pm context --parent <id> --depth deep` |
+| Relevant items | `pm search "<keywords>" --limit 10` (keyword hits are score-ranked; keyword mode defaults to 50 results, `result.total` reports the full pre-limit count) |
+| Require every query token | `pm search "<keywords>" --match-mode and` (hard-filter; `exact` = contiguous phrase; default `or` adds an all-terms ranking bonus) |
+| Just the match count | `pm search "<keywords>" --count` (no hit rows; `count`/`total` carry the matched total) |
+| Per-query score threshold | `pm search "<keywords>" --min-score 5` (overrides settings `search.score_threshold` for this query) |
+| Every matched row (no cap) | `pm list --all --no-truncate --brief` (`result.total` reports the full count when a `--limit`/`--offset` truncates) |
+| Item bodies in bulk (one call) | `pm list --status open --json --include-body` (avoids one `pm get` per item) |
+| Open work only | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos) |
+| Scope search like list | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity) |
+| Items changed since last window | `pm list --all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work) |
+| Open items changed today | `pm list --status open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`) |
+| Items changed recently | `pm list --all --recent --brief` (last seven days; mutually exclusive with `--updated-after`) |
+| Single item | `pm get <id>` |
+| Full machine payload | `pm get <id> --full --json` |
+| Command flags | `pm <command> --help --json` |
+| Command intent map | `pm contracts --summary --json` (one command plus terse intent per row; use before command-scoped contracts) |
+| Low-noise machine contracts | `pm contracts --command <command> --flags-only --json` |
+| Semantic index refresh | `pm reindex --mode semantic --progress` (stale-first by default; add `--full` to force full rebuild; requires the `search-advanced` package) |
+| Timeline | `pm activity --id <id> --limit 20` |
+| Audited history redaction | `pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run` |
+| Audited history re-anchor | `pm history-repair <id> --dry-run` (clears drift flagged by `pm health`/`pm validate`) |
+| Register custom item type | `pm schema add-type <Name> --description "<text>" --default-status open` (then `pm create <Name> "..."`) |
+| Remove custom item type | `pm schema remove-type <Name>` (warns if items still use it; built-ins refused) |
+| Register custom status | `pm schema add-status <id> --role <active\|terminal\|...> --alias <name> --order <n>` |
+| Remove custom status | `pm schema remove-status <id>` (warns if items use it; built-in statuses refused) |
+| Agent plan create | `pm plan create --title "<scope>" --harness claude-code --scope "<short>" --claim` |
+| Agent plan create with steps | `pm plan create --title "<scope>" --step "<step 1>" --step "<step 2>" --step "<step 3>"` (repeated `--step` seeds ordered steps) |
+| Agent plan step update | `pm plan update-step <plan-id> plan-step-001 --step-status in_progress --step-evidence "<short>"` |
+| Agent plan read | `pm plan show <plan-id> --depth brief` (or `--fields id,title,steps_summary`) |
+| Materialize plan steps | `pm plan materialize <plan-id> --steps plan-step-002 --materialize-type Task` |
+| Dependencies | `pm deps <id> --format tree` |
+| Graph queries | `pm graph successors <id> --limit 20` (also `ancestors`, `paths`, `impact`, `analyze`, `audit`, `communities`, `redundancy`, `dominators`, `plan`) |
+| Bulk update by id allowlist | `pm update-many --ids pm-a,pm-b --priority 1 --dry-run` (preview, then drop `--dry-run`) |
+| Audited bulk close (sprint closeout) | `pm close-many --filter-sprint <s> --reason "<text>" --dry-run` (full `pm close` semantics per item; `--rollback <id>` to undo) |
+| Local docs routing | `pm install guide-shell --project`, then `pm guide <topic>` |
+| Compact mutation echo | `pm --no-changed-fields create "..."` (drops the redundant `changed_fields` array, keeps `changed_field_count`) |
+| Minimal mutation echo | `pm --id-only create "..."` (prints only id and status for single-item mutations) |
+| Duplicate close | `pm close <duplicate> --duplicate-of <canonical>` (or `-d <canonical>`) |
+| Long body from a file | `pm create <Type> "<title>" --body-file ./spec.md` (also on `pm update`; mutually exclusive with `--body`) |
+| Close with short flags | `pm close <id> -r "<reason>"` / `-m "<history msg>"` / `-d <canonical>` |
+| Close via resolution only | `pm close <id> --resolution "<summary>"` (used as the close reason when one is required) |
 
 Default TOON output is preferred for model-readable loops. Use `--json` only when strict parsing is needed.
 

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`).
 
@@ -963,6 +963,118 @@ pm release <id>
 `--author` on claim/release flows, not a metadata update. Use `--force` only when
 explicitly overriding terminal-state or lock conflicts.
 
+Starting work respects declared blockers
+([pm-urzubi](../.agents/pm/issues/pm-urzubi.toon)). `pm update <id> --status
+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. `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
+refuses and, if it took the item from no owner, releases that claim. The release
+is fenced by assignee and claim principal, so another principal's takeover is
+never cleared; principal is pm's unit of ownership, so a concurrent reclaim by
+the same principal is indistinguishable from the original claim. If the item already had an owner, or that
+release cannot run, the claim stays and the refusal's `why` reports the partial
+completion. The
+refusal lists the open blockers in `details.open_blockers` and suggests the
+exact `pm update` that drops the edge. When no single command can do that
+safely (clearing the `blocked_by` scalar would also drop an independent
+`blocked_by` edge, or a legacy row's short id, alias kind or external locator
+would not match a removal selector; see
+[pm-4yxzvd](../.agents/pm/issues/pm-4yxzvd.toon)), it suggests inspecting the
+item instead. The check uses the effective start status, including the
+registered `in_progress` fallback when the workflow names `open`.
+A terminal blocker never blocks, and an update that removes the blocker in the
+same call is admitted. `--force` starts anyway and records
+`start_blocker_override:<id>:<blockers>`. `governance.start_blocker_enforcement`
+selects `strict` (default), `warn` (start and record
+`start_with_open_blockers:<id>:<blockers>`), or `off`. A blocker whose record
+cannot be judged (an invalid or non-UTF-8 document, an unsupported item format,
+or an ambiguous or conflicting identity) refuses under `strict` with that typed
+error. `warn` and `--force` still admit the start and record
+`start_blocker_unverifiable:<id>:<code>`. Filesystem failures and merge-conflict
+markers always propagate.
+
+### Expected revisions (`--expect-hash`)
+
+Read-decide-write agents guard a write with the revision they decided on
+([pm-gh1576](../.agents/pm/features/pm-gh1576.toon)). `pm get <id> --json`
+reports `item_hash`. The global `--expect-hash <item_hash>` flag makes every
+locked write the command makes to that item refuse with `item_revision_conflict`
+(exit 4) if the item changed since:
+
+```bash
+H=$(pm get pm-a1b2 --json | jq -r .item_hash)
+pm close pm-a1b2 "Delivered by PR 1" --expect-hash "$H"
+H1=$(pm get pm-a1b2 --json | jq -r .item_hash)
+H2=$(pm get pm-c3d4 --json | jq -r .item_hash)
+pm update-many --ids pm-a1b2,pm-c3d4 --priority 1 \
+  --expect-hash "pm-a1b2=$H1" --expect-hash "pm-c3d4=$H2"
+```
+
+A bare hash binds to the command's `<id>` argument (for `plan`, the id after
+the subcommand; `plan create` has none). `<id>=<item_hash>`
+(repeatable or comma-separated) names targets explicitly and is required for
+commands without one item argument. The refusal reports `expected_revision`,
+`current_revision`, and `details.changes_since` (the newest 10 history entries
+since the declared revision, with their top-level `fields`). The refused write
+is suppressed; writes the same command already committed (for example the
+claim of a composed `claim --start`) stay durable, and the message then says
+so ("Earlier writes by this same invocation already committed"). Read commands refuse the flag with
+`expect_hash_requires_mutation`, and an empty value (such as an unset `$H`)
+refuses with `expect_hash_invalid` instead of running unguarded. Bulk
+`update-many`/`close-many` fail only stale rows, forward and `--rollback` alike, each
+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. 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
+recovers it. `deps` only reads, so it refuses the flag. History maintenance
+(`history-redact`, `history-repair` including `--salvage-tail`, `history-compact`)
+is checked under the stream lock. Its bulk forms (`history-compact --ids`,
+`history-repair --all`) carry the same typed conflict fields on refused rows. An
+item file whose embedded id differs from its physical file name (even by case on a
+case-sensitive filesystem) binds no revision: reading or declaring one refuses with
+`item_identity_conflict` until the identity is repaired. `validate --auto-fix`/`--prune-missing` refuses typed once every fix
+was attempted. When an extension parser or preflight override rewrites the
+invocation's tracker or arguments, a guarded invocation refuses with
+`expect_hash_invocation_rewritten`, since which item it writes cannot be proved.
+The same refusal covers a parser pass during final dispatch, which must also keep
+the guard admissible (adding `--background` late refuses with
+`expect_hash_background_unsupported`). Inventory commands
+(`package inventory`, `extension inventory`) never write items, so they validate
+the flag and then refuse with `expect_hash_requires_mutation`. An item the command never wrote produces the
+warning `expect_hash_unchecked:<id>:no_locked_write_reached_this_item`. MCP
+tools accept the same tokens as `expectHash`; the SDK exposes
+`withExpectedItemRevisions` (see [SDK](SDK.md#expected-item-revisions)).
+
 ## Logs
 
 ```bash
@@ -1487,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 |