@unbrained/pm-cli 2026.5.1 → 2026.5.3-5

package/README.md

@@ -5,87 +5,22 @@
 [![Node >=20](https://img.shields.io/node/v/%40unbrained%2Fpm-cli)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-`pm` is a git-native project management CLI for humans and coding agents. It stores items as TOON (`.toon`) by default with full first-class JSON-front-matter Markdown (`.md`) support, keeps append-only JSONL history, and supports safe collaboration.
+`pm` is a git-native project management CLI for humans and coding agents. It stores work items in reviewable repository files, records every mutation in append-only history, and defaults to sparse TOON output so agents can spend fewer tokens while still getting deterministic data.
 
-## Highlights
+## Start Here
 
-- Git-native items that stay reviewable in diffs
-- Safe multi-agent workflows with claims, locks, and restore
-- Deterministic output with TOON by default and `--json` when needed
-- Layered command help: compact default (`Intent` + one example) and deep explainability via `--explain`
-- Machine-readable help payloads via `pm <command> --help --json` (also `pm help <command> --json`)
-- Structured diagnostics with machine-readable JSON error envelopes when `--json` is active
-- Dedicated machine contract surface via `pm contracts` (`--action`, `--command`, `--schema-only`, `--runtime-only`, `--active-only`)
-- Sparse TOON default output that omits null/undefined/empty fields for token-efficient agent workflows
-- Agent-friendly calendar views (`pm calendar` / `pm cal`) with markdown default output
-- Agent-first context snapshot command (`pm context` / `pm ctx`) for critical work + agenda triage
-- Reusable create templates (`pm templates save/list/show` + `pm create --template`)
-- First-class dual item storage formats: TOON (`.toon`) and JSON-front-matter Markdown (`.md`)
-- Compact TOON documents that are easier to review in terminal and GitHub web UI
-- Automatic item format migration when `item-format` config changes
-- Deterministic canonical normalization and atomic writes for parallel git/worktree workflows
-- Warning-first/strict validation policies for sprint/release and parent references
-- Additive history diff/verify diagnostics (`pm history --diff --verify`)
-- Linked path hygiene for files/docs (`--add-glob`, `--migrate`, `--validate-paths`, `--audit`)
-- Dependency topology inspection via `pm deps --format tree|graph`
-- Deterministic `--tag` completion suggestions from tracked item metadata
-- Additive large-list controls via projection (`--compact` / `--fields`), configurable sorting (`--sort` + `--order`), pagination (`--offset`), and opt-in JSON streaming (`--stream` with `--json`)
-- Governance-focused corpus analysis commands: `pm aggregate` default grouped counts and `pm dedupe-audit` duplicate clustering
-- Standalone `pm validate` command for metadata, resolution, lifecycle, linked-file, linked-command reference, and history-drift audits
-- Opt-in non-interactive progress output for long-running operations (`pm test`, `pm test-all`, `pm reindex` with `--progress`)
-- Managed background linked-test orchestration (`pm test --run --background`, `pm test-all --background`, and `pm test-runs` lifecycle controls; bare `pm test-runs` defaults to list output)
-- Linked-test context preflight and auto-remediation controls (`pm test`/`pm test-all` with `--check-context` and `--auto-pm-context`)
-- Safer cache cleanup controls via `pm gc --dry-run` and scoped cleanup with `--scope index|embeddings|runtime`
-- Pager-safe help output in automation (help requests auto-disable paging on non-TTY stdout, with explicit global `--no-pager` override)
-- Settings-gated item-level test result tracking (`pm config ... test-result-tracking --policy enabled|disabled`)
-- Optional search and extension support for more advanced setups
+| Need | Read |
+|------|------|
+| Install and create the first item | [Quickstart](docs/QUICKSTART.md) |
+| Agent workflow and token-minimal loops | [Agent Guide](docs/AGENT_GUIDE.md) |
+| Command families and examples | [Command Reference](docs/COMMANDS.md) |
+| Settings, storage, search, and output | [Configuration](docs/CONFIGURATION.md) |
+| Safe test execution and linked tests | [Testing](docs/TESTING.md) |
+| Extension authoring | [Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) |
+| Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md) |
+| Contributor internals | [Architecture](docs/ARCHITECTURE.md) |
 
-## Unified Command Contracts
-
-`pm` now centralizes command/action contract metadata in `src/sdk/cli-contracts.ts` and uses it across:
-
-- CLI option normalization in `src/cli/main.ts`
-- Shell completion generation in `src/cli/commands/completion.ts`
-- Pi wrapper tool actions, JSON Schema, and arg mapping in `.pi/extensions/pm-cli/index.ts`
-
-Compatibility policy for command contracts:
-
-- Existing commands/flags and aliases remain valid.
-- Pi tool schema now uses strict action-scoped branches (schema v4); callers should send only action-relevant fields.
-- `--json` remains machine-contract stable; search projection defaults are command-specific (`pm search` defaults to compact rows unless `--full` is requested).
-- `pm contracts --json` is the canonical runtime contract introspection surface for agents, including active extension command/action metadata.
-- Contract payloads include runtime action availability metadata (`action_availability`) and optional runtime-filtered views (`--runtime-only`, `--active-only`) so automation can avoid non-invocable actions.
-- `pm contracts --command <name>` scopes output to the selected command for lower-noise machine payloads; omit `--command` for the full contract corpus.
-- `pm contracts` supports lightweight projection modes for automation pipelines: `--flags-only` (command flag surface) and `--availability-only` (runtime invocability metadata); the projection flags are mutually exclusive.
-- When `--action` is provided without `--command`, `pm contracts --flags-only` now scopes `command_flags` to the action-mapped command surface (for example `test-runs-list` resolves to `test-runs`).
-- Contract payloads include canonical flag + alias metadata (`command_flags` plus `commander_aliases`) so machine clients can expose accepted hyphen/underscore variants deterministically.
-- `pm completion` scripts are generated from the same normalized command-contract registry used by parser/contracts, keeping runtime, contract, and completion parity aligned.
-- `pm completion` now defaults to lazy tag expansion through runtime `pm completion-tags` lookup in generated scripts; pass `--eager-tags` to embed static tags in the script (legacy eager mode).
-
-## Item Storage Formats
-
-- Default item format is TOON (`.toon`) using root-object field storage (`id`, `title`, ..., `body`).
-- JSON front matter + markdown body (`.md`) is a fully supported alternative format.
-- `front_matter` is an internal TypeScript field name (`ItemDocument.front_matter`) for item metadata; TOON files store the same metadata as top-level keys, not YAML front matter.
-- History files always remain JSONL (`history/<id>.jsonl`).
-- Set project item storage format with:
-
-```bash
-pm config project set item-format --format toon
-# or
-pm config project set item-format --format json_markdown
-```
-
-Changing `item-format` automatically migrates item files to the configured format.
-
-## Parallel Git and Worktree Robustness
-
-- TOON and JSON/Markdown are equally supported item formats; teams can choose either format per repository.
-- Canonical normalization (stable field ordering and deterministic serialization) reduces diff churn and helps keep merges predictable.
-- Item writes are atomic (temp file + rename), which prevents partial writes and corruption during concurrent local operations.
-- Item history remains append-only JSONL with before/after hashes, so changes are auditable and recoverable with `pm history` and `pm restore`.
-- When both `.toon` and `.md` exist for one item ID, configured `item_format` is the source of truth and automatic migration removes split-format drift.
-- Concurrent edits to the exact same content can still require normal git conflict resolution; the storage model is designed to avoid silent data loss and make reconciliation explicit.
+Full documentation starts at [docs/README.md](docs/README.md).
 
 ## Install
 
@@ -97,1060 +32,81 @@ pm --version
 pm --help
 ```
 
-For project-local use:
+Project-local invocation also works:
 
 ```bash
 npx @unbrained/pm-cli --help
 ```
 
-## Quick Start
+## 60 Second Example
 
 ```bash
 pm init
 
 pm create \
-  --title "Fix Windows restore failure after stale lock cleanup" \
-  --description "Restore can fail on Windows when a stale lock is cleaned up during retry." \
+  --title "Fix stale lock restore failure" \
+  --description "Restore should retry cleanly after stale lock cleanup." \
   --type Issue \
   --status open \
   --priority 1 \
-  --tags "windows,locks,restore,release" \
-  --body "Users can reproduce this on Windows after an interrupted restore. Add retry logging and verify restore succeeds after stale lock cleanup." \
-  --deadline +3d \
-  --estimate 180 \
-  --acceptance-criteria "Restore succeeds after stale lock cleanup on Windows and regression coverage is added." \
-  --definition-of-ready "Owner, reproduction steps, and affected files are identified." \
-  --order 7 \
-  --goal "Release readiness" \
-  --objective "Stabilize restore under lock contention" \
-  --value "Reduces failed recovery workflows during real incidents" \
-  --impact "Fewer blocked releases and clearer operator recovery steps" \
-  --outcome "Restore completes reliably after stale lock cleanup" \
-  --why-now "The bug affects recovery flows and can block release work." \
-  --author "alex-maintainer" \
-  --message "Create restore failure issue with full metadata" \
-  --assignee "alex-maintainer" \
-  --parent "pm-release" \
-  --reviewer "sam-reviewer" \
-  --risk high \
-  --confidence medium \
-  --sprint "2026-W11" \
-  --release "v2026.3" \
-  --blocked-by "pm-locks" \
-  --blocked-reason "Need the lock cleanup refactor merged first" \
-  --unblock-note "Rebase once the lock cleanup patch lands" \
-  --reporter "qa-bot" \
-  --severity high \
-  --environment "windows-11 node-25 npm-global-install" \
-  --repro-steps "1) Interrupt restore after lock creation 2) Retry restore 3) Observe stale-lock cleanup fail on Windows" \
-  --resolution "Add a retry after stale-lock cleanup and log the recovery path" \
-  --expected-result "Restore retries cleanly and completes after stale-lock cleanup." \
-  --actual-result "Restore exits with a lock error after cleanup on Windows." \
-  --affected-version "2026.3.9" \
-  --fixed-version "2026.3.10" \
-  --component "core/locks" \
-  --regression true \
-  --customer-impact "Maintainers can be blocked from recovering work during release prep." \
-  --dep "id=pm-locks,kind=blocks,author=alex-maintainer,created_at=now" \
-  --comment "author=alex-maintainer,created_at=now,text=Initial triage confirms the Windows-only stale-lock recovery failure." \
-  --note "author=alex-maintainer,created_at=now,text=Investigate lock cleanup timing in the restore retry path." \
-  --learning "author=alex-maintainer,created_at=now,text=Windows file-handle timing needs a retry window after stale-lock cleanup." \
-  --file "path=src/core/lock/lock-store.ts,scope=project,note=likely stale-lock retry fix" \
-  --test "command=node scripts/run-tests.mjs test -- tests/integration/cli.integration.spec.ts,scope=project,timeout_seconds=900,note=restore lock regression coverage" \
-  --doc "path=docs/ARCHITECTURE.md,scope=project,note=lock and restore design context"
+  --tags "restore,locks" \
+  --ac "Restore succeeds after stale lock cleanup and has regression coverage." \
+  --create-mode progressive
 
 pm list-open --limit 10
 pm claim <item-id>
+pm update <item-id> --status in_progress --message "Start implementation"
+pm files <item-id> --add path=src/core/lock/lock.ts,scope=project
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",scope=project,timeout_seconds=240
+pm test <item-id> --run --progress
+pm close <item-id> "Fixed stale lock retry path; linked test passed."
+pm release <item-id>
 ```
 
-From there, use `pm update`, `pm comments`, `pm notes`, `pm learnings`, `pm files`, `pm docs`, `pm test`, `pm search`, and `pm close` as work progresses.
-
-Claim behavior note:
-
-- `pm claim <ID>` can take over non-terminal items even when currently assigned to someone else.
-- Use `--force` for claim/release only when overriding terminal-state or lock conflicts.
-- For non-owner release handoffs that only clear assignee metadata, prefer `pm release <ID> --allow-audit-release --author <you>` before `--force`.
-- For ownership-conflict mutations, `--force` is intended for coordinated PM audits, lead-maintainer metadata corrections, or explicit ownership handoff cleanup.
-- `pm get <ID> --json` now includes `claim_state` with current assignee plus latest claim/release history context.
-- `pm get <ID> --json` returns body at top-level key `body` (not `item.body`) alongside `item`, `linked`, and `claim_state`.
-
-Create policy mode note:
+## Agent Loop
 
-- `pm create` defaults to strict required-option enforcement.
-- Use `--create-mode progressive` for staged governance triage when you need to defer non-critical metadata/linkage fields without placeholder `none` entries.
+Use `pm context` first, then search before creating anything:
 
 ```bash
-pm create --title "Triage seed" --description "Capture scope first, enrich later" --type Task --create-mode progressive
+pm context --limit 10
+pm search "keywords for the requested work" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
 ```
 
-## Reusable Create Templates
+If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).
 
-Use templates to save recurring create metadata (including repeatable seeds) and apply them with explicit override precedence:
+## Release Automation
 
-Template names are positional arguments (`pm templates save <name>` / `pm templates show <name>`); `--name` is not a valid flag.
+- Daily release preparation runs in `.github/workflows/auto-release.yml`.
+- Tag-driven publishing remains in `.github/workflows/release.yml`.
+- Local parity commands:
+  - `pnpm release:pipeline:dry-run`
+  - `pnpm release:pipeline -- --telemetry-mode required`
 
-```bash
-pm templates save release-issue \
-  --type Issue \
-  --status open \
-  --priority 1 \
-  --tags "release,incident" \
-  --dep "id=pm-release,kind=related,created_at=now" \
-  --file "path=src/cli/main.ts,scope=project"
+## Core Model
 
-pm templates list
-pm templates show release-issue --json
+- Items live under `.agents/pm/` as TOON by default, with JSON-front-matter markdown also supported.
+- History lives in `.agents/pm/history/<id>.jsonl` and is append-only.
+- Statuses are `draft`, `open`, `in_progress`, `blocked`, `closed`, and `canceled`.
+- Built-in types include `Epic`, `Feature`, `Task`, `Chore`, `Issue`, `Decision`, `Event`, `Reminder`, `Milestone`, and `Meeting`.
+- Output defaults to sparse TOON. Use `--json` for strict parsing.
+- `pm contracts` is the machine-readable command and schema contract surface for agents.
 
-# Explicit flags override template defaults deterministically.
-pm create \
-  --title "Follow-up issue" \
-  --description "Investigate release incident follow-up." \
-  --type Issue \
-  --template release-issue \
-  --status blocked
-```
-
-## Semantic Search Defaults (Ollama)
-
-`pm search` now auto-enables semantic-capable defaults on hosts where local Ollama is installed, without requiring manual semantic provider/vector configuration in `settings.json`.
-
-- Auto-defaults only apply when semantic settings are otherwise unset (no explicit `settings.search.provider`, `settings.vector_store.adapter`, `providers.*`, or `vector_store.*` semantic config).
-- Resolved defaults are:
-  - embedding provider: Ollama (`http://localhost:11434`)
-  - embedding model: `PM_OLLAMA_MODEL` (if set), otherwise first model from `ollama list` (preferring names containing `embed`/`embedding`), otherwise `qwen3-embedding:0.6b`
-  - vector store: local LanceDB path `.agents/pm/search/lancedb/`
-- Explicit user/project configuration always takes precedence over auto-defaults.
-- If implicit auto-defaulted semantic execution fails at runtime, `pm search` falls back to keyword mode to avoid breaking existing users.
-- Implicit hybrid auto-default execution now uses bounded semantic timeouts and adds deterministic fallback warnings (for example `search_implicit_semantic_fallback:timeout:using_keyword_mode`) when switching to keyword mode.
-- For strict low-latency loops, use `--mode keyword` explicitly.
-- Disable this behavior with `PM_DISABLE_OLLAMA_AUTO_DEFAULTS=1`.
-
-To (re)build semantic artifacts explicitly:
-
-```bash
-pm reindex --mode hybrid
-```
-
-## Search Projection Modes
+## Tracker References
 
-`pm search` now supports explicit projection controls and defaults to compact rows in both TOON and JSON output modes:
-
-- default projection: compact (`id`, `title`, `status`, `type`, `priority`, `updated_at`, `score`, `matched_fields`)
-- `--full`: return full hit rows (including nested `item` payload)
-- `--fields <csv>`: return only specific fields (for example `--fields id,title,score,item.updated_at`)
-- projection flags are mutually exclusive (`--compact`, `--full`, `--fields`)
-
-Unquoted multi-word queries are accepted directly:
-
-```bash
-pm search performance mobile gpu --limit 5
-```
-
-## Hierarchical List Filtering
-
-All list-family commands now support parent-scoped filtering:
-
-```bash
-pm list-open --parent pm-epic01 --limit 20
-pm list-in-progress --parent pm-feature02 --json
-```
-
-## List Projection and Sorting
-
-List-family commands support explicit projection and deterministic sort controls:
-
-```bash
-# Compact default projection fields for list rows
-pm list-open --compact --limit 20
-
-# Custom projected fields
-pm list-all --fields id,title,parent,type --limit 50
-
-# Configurable sort field + order
-pm list-open --sort deadline --order asc --limit 20
-pm list-open --sort priority --order desc --limit 20
-```
-
-Projection flags are mutually exclusive for list-family commands (`--compact`, `--fields`, `--include-body` remains additive for body projection).
-
-## Ownership-Safe Metadata Updates and Bulk Mutation
-
-Governance workflows now include explicit non-owner metadata mutation and bulk update planning surfaces:
-
-- `pm update --allow-audit-update` allows non-owner metadata updates without broad `--force` semantics.
-- `--allow-audit-update` is intentionally scoped: lifecycle/ownership/linkage mutations remain disallowed in this mode (for example assignee/parent and other lifecycle-governing fields).
-- `pm update --allow-audit-dep-update` enables non-owner append-only dependency additions via `--dep` without broad `--force` semantics.
-- `--allow-audit-update` and `--allow-audit-dep-update` are mutually exclusive by design.
-- `pm update-many` provides native bulk mutation with deterministic filter targeting, dry-run planning, optional checkpoint capture, and rollback.
-- `pm update-many` supports linked-array payload parity with `pm update` (repeatable `--dep/--comment/--note/--learning/--file/--test/--doc/--reminder/--event` plus `--clear-*`, `--replace-deps`, and `--replace-tests`).
-- `pm update-many --rollback <checkpoint-id>` restores every item in a prior checkpoint (ownership-safe restore path included).
-- `pm normalize` provides deterministic lifecycle metadata hygiene with default dry-run planning and explicit `--apply` mode.
-- `pm normalize` reuses list-style filter targeting (`--filter-status`, `--filter-type`, `--filter-tag`, assignee/parent/sprint/release, `--limit`, `--offset`) and supports ownership-safe apply controls (`--allow-audit-update`, `--force`).
-
-```bash
-# Ownership-safe metadata audit update (non-owner, metadata-only scope)
-pm update pm-a1b2 --description "Clarified acceptance boundaries" --allow-audit-update --author audit-maintainer
-
-# Ownership-safe dependency-only audit update (append-only --dep)
-pm update pm-a1b2 --dep "id=pm-epic01,kind=related,author=audit-maintainer,created_at=now" --allow-audit-dep-update --author audit-maintainer
-
-# Bulk apply mode with deterministic targeting
-pm update-many --filter-status open --filter-tag governance --status in_progress --author maintainer --message "Governance sweep"
-
-# Bulk linked-test replacement across matched items (single transaction per item)
-pm update-many --filter-tag wave:7 --replace-tests --test "command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,scope=project,timeout_seconds=240" --message "Normalize linked test assertions"
-
-# Dry-run planning mode (no mutations)
-pm update-many --filter-status in_progress --priority 1 --deadline +2d --dry-run --json
-
-# Roll back a previously captured checkpoint
-pm update-many --rollback 20260406T102455Z-7xq9 --author maintainer --message "Rollback governance batch"
-
-# Preview lifecycle metadata normalization plans (default mode is dry-run)
-pm normalize --filter-status in_progress --dry-run --json
-
-# Apply lifecycle metadata normalization with audit-safe ownership controls
-pm normalize --filter-tag governance --apply --allow-audit-update --author maintainer --message "Normalize lifecycle metadata"
-```
-
-## Duplicate and Decomposition Audits
-
-Governance workflows now have dedicated audit commands:
-
-```bash
-# Group child counts by parent/type for decomposition checks
-pm aggregate --group-by parent,type --status open --json
-
-# Include rows that do not have a parent when grouping by parent
-pm aggregate --group-by parent,type --include-unparented --json
-
-# Group by operational triage dimensions
-pm aggregate --group-by type,status --json
-
-# Detect likely duplicates by exact title, fuzzy title, or parent-scoped title collisions
-pm dedupe-audit --mode title_exact --limit 25 --json
-pm dedupe-audit --mode title_fuzzy --threshold 0.75 --limit 25 --json
-pm dedupe-audit --mode parent_scope --limit 25 --json
-```
-
-`pm aggregate --group-by` supports `parent,type,priority,status,assignee,tags,sprint,release`.
-
-## GC Safety Controls
-
-`pm gc` now supports no-side-effect previews and targeted cleanup scopes:
-
-```bash
-# Preview what would be removed (no deletes)
-pm gc --dry-run --json
-
-# Clean only index + embeddings cache artifacts
-pm gc --scope index,embeddings --json
-
-# Repeatable scope flags are also supported
-pm gc --scope runtime --scope embeddings --json
-```
+This documentation refresh is tracked through `pm`:
 
-`pm gc` output now includes `dry_run`, resolved `scope`, and `guidance` fields. When search artifacts are removed, guidance includes reindex recommendations.
+- [pm-3042](.agents/pm/epics/pm-3042.toon) - documentation overhaul epic
+- [pm-r9gu](.agents/pm/features/pm-r9gu.toon) - documentation structure feature
+- [pm-1sb2](.agents/pm/tasks/pm-1sb2.toon) - README and public docs rewrite task
 
-## Health Drift, Integrity, and Vectorization Checks
-
-`pm health` includes deterministic checks for item/history integrity and semantic vector freshness:
-
-- `directories`
-  - distinguishes required tracker directories from optional built-in item-type directories
-  - reports `missing_required` and `missing_optional` separately in check details
-  - treats missing optional built-in type directories (`events`, `reminders`, `milestones`, `meetings`) as informational by default
-  - supports `--strict-directories` to treat missing optional directories as health warnings/failures
-  - supports `--strict-exit` (alias `--fail-on-warn`) to return non-zero exit (`1`) when health warnings are present (`ok=false`)
-- `integrity`
-  - scans item and history files for merge-conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
-  - reports invalid item parses and invalid JSONL lines in history streams with deterministic warning codes
-- `history_drift`
-  - scans current items and compares each canonical item hash against the latest history `after_hash`
-  - reports missing history streams, unreadable/corrupt history streams, and hash mismatches
-- `vectorization`
-  - compares current item `updated_at` values against a local vectorization ledger at `search/vectorization-status.json`
-  - identifies stale/missing vector entries and (by default) performs targeted semantic refresh for stale item IDs when semantic runtime is available
-  - avoids forcing a full rebuild (`pm reindex`) for routine health checks
-  - supports explicit refresh policy controls:
-    - `--check-only` / `--no-refresh` for read-only diagnostics
-    - `--refresh-vectors` to force refresh intent explicitly
-
-The vectorization ledger is also refreshed during `pm reindex --mode semantic|hybrid` to keep health diagnostics aligned with the latest indexed corpus.
-
-## Standalone Validation Checks
-
-`pm validate` provides a dedicated audit surface for project metadata quality and integrity checks:
-
-- Runs all validation checks by default (`metadata`, `resolution`, `lifecycle`, `files`, `command_references`, `history_drift`).
-- Runs linked-command PM reference checks by default (`command_references`) to catch stale `pm-<id>` references before execution-time failures.
-- Supports scoped checks with `--check-metadata`, `--check-resolution`, `--check-lifecycle`, `--check-stale-blockers`, `--check-files`, `--check-command-references`, and `--check-history-drift`.
-- `--check-metadata` supports `--metadata-profile core|strict|custom` for deterministic required-field policy selection.
-- `--metadata-profile custom` reads `settings.validation.metadata_required_fields`; if the configured list is empty, validation falls back to core requirements and emits `validate_metadata_custom_profile_missing_required_fields:0`.
-- `--check-lifecycle` audits active-item governance drift for terminal-parent lineage and closure-like metadata on non-terminal items.
-- `--check-stale-blockers` adds optional blocker-consistency diagnostics to lifecycle checks, surfacing stale `blocked_by`/`blocked_reason` patterns without enabling those heuristics by default.
-- Lifecycle-check details include effective closure/stale pattern lists and deterministic per-field pattern sources (`default` vs `settings`).
-- `--check-files` supports `--scan-mode default|tracked-all|tracked-all-strict`; tracked modes use git-tracked candidates when available.
-- `tracked-all` excludes PM internals by default for higher-signal orphaned results; pass `--include-pm-internals` for full internal-audit scans.
-- `tracked-all-strict` forces full tracked coverage (including PM internals) and bypasses internal exclusion filtering.
-- `tracked-all-strict` emits explicit strict-coverage visibility fields in file-check details (`strict_mode_forces_pm_internals`, `strict_mode_forces_pm_internals_notice`) and warning `validate_files_tracked_all_strict_forces_pm_internals` when internals were force-enabled.
-- File-check details report filtered candidate counts (`candidate_total`, `candidate_scanned`) plus raw pre-filter counts (`candidate_total_raw`, `candidate_scanned_raw`), `pm_internal_excluded_count`, and structured `excluded_by_reason` summaries when paths are filtered.
-- Command-reference details report referenced PM IDs and stale-reference rows; stale rows emit `validate_command_references_stale_pm_ids:<count>` warnings.
-- Resolution-check details now include default remediation hint templates (`pm update <id> ...`) for missing `resolution`/`expected_result`/`actual_result` fields.
-- `--strict-exit` (alias `--fail-on-warn`) returns non-zero exit (`1`) when validation warnings are present (`ok=false`).
-- Returns deterministic TOON/JSON output suitable for review or automation pipelines.
-- Output writers treat broken pipes (`EPIPE`) as expected shell behavior: stdout `EPIPE` exits successfully (for pipeline-friendly reads) while stderr `EPIPE` remains non-zero.
-
-## Missing History Stream Policy
-
-`settings.history.missing_stream` controls behavior when an item's `history/<id>.jsonl` stream is missing:
-
-- `auto_create` (default)
-  - missing streams for existing items are created automatically before history-touching command paths continue
-- `strict_error`
-  - history-touching command paths fail with a deterministic error instead of creating missing streams
-
-Configure policy with:
-
-```bash
-pm config project set history-missing-stream-policy --policy auto_create
-pm config project set history-missing-stream-policy --policy strict_error
-pm config project get history-missing-stream-policy --json
-```
-
-Policy enforcement applies to `pm history`, `pm activity`, `pm stats`, `pm health`, restore, and existing-item mutation paths.
-
-## Sprint/Release Format Policy
-
-`settings.validation.sprint_release_format` controls `--sprint` and `--release` validation behavior during `pm create` and `pm update`:
-
-- `warn` (default)
-  - accepts non-conforming values and emits deterministic warnings (`validation_warning:sprint_format:<value>` / `validation_warning:release_format:<value>`)
-- `strict_error`
-  - rejects non-conforming values with a deterministic usage error
-
-Accepted format for conforming values: 1-64 characters matching `[A-Za-z0-9][A-Za-z0-9._/-]*` (no spaces).
-
-Configure policy with:
-
-```bash
-pm config project set sprint-release-format-policy --policy warn
-pm config project set sprint-release-format-policy --policy strict_error
-pm config project get sprint-release-format-policy --json
-```
-
-## Parent Reference Validation Policy
-
-`settings.validation.parent_reference` controls how `--parent` behaves during `pm create` and `pm update` when the referenced parent item does not exist:
-
-- `warn` (default)
-  - keeps backward-compatible behavior and emits `validation_warning:parent_reference_missing:<id>`
-- `strict_error`
-  - rejects missing parent references with a deterministic usage error
-
-Configure policy with:
-
-```bash
-pm config project set parent-reference-policy --policy warn
-pm config project set parent-reference-policy --policy strict_error
-pm config project get parent-reference-policy --json
-```
-
-## Metadata Validation Profile Policy
-
-`settings.validation.metadata_profile` controls default required-field behavior for `pm validate --check-metadata`:
-
-- `core` (default)
-  - requires baseline governance fields (`author`, `acceptance_criteria`, `estimated_minutes`, `close_reason` for closed items)
-- `strict`
-  - extends core checks with additional governance fields (`reviewer`, `risk`, `confidence`, `sprint`, `release`)
-- `custom`
-  - uses `settings.validation.metadata_required_fields` as the required field set (falls back to core + warning when empty)
-
-Configure policy with:
-
-```bash
-pm config project set metadata-validation-profile --policy core
-pm config project set metadata-validation-profile --policy strict
-pm config project set metadata-validation-profile --policy custom
-pm config project get metadata-validation-profile --json
-```
-
-Configure custom required fields with:
-
-```bash
-pm config project set metadata-required-fields --criterion sprint --criterion release
-pm config project set metadata-required-fields --clear-criteria
-pm config project get metadata-required-fields --json
-```
-
-## Lifecycle Validation Pattern Policy
-
-`settings.validation.lifecycle_*_patterns` controls default substring heuristics used by `pm validate --check-lifecycle` and optional stale blocker diagnostics (`--check-stale-blockers`):
-
-- `settings.validation.lifecycle_stale_blocker_reason_patterns`
-  - stale blocker reason substrings matched when stale blocker checks are enabled
-- `settings.validation.lifecycle_closure_like_blocked_reason_patterns`
-  - closure-like `blocked_reason` substrings flagged on active items
-- `settings.validation.lifecycle_closure_like_resolution_patterns`
-  - closure-like `resolution` substrings flagged on active items
-- `settings.validation.lifecycle_closure_like_actual_result_patterns`
-  - closure-like `actual_result` substrings flagged on active items
-
-Configure lifecycle patterns with:
-
-```bash
-pm config project set lifecycle-stale-blocker-reason-patterns --criterion "no active blocker"
-pm config project set lifecycle-closure-like-blocked-reason-patterns --criterion "work is closed"
-pm config project set lifecycle-closure-like-resolution-patterns --criterion "closed with implementation evidence"
-pm config project set lifecycle-closure-like-actual-result-patterns --criterion "work completed"
-pm config project set lifecycle-closure-like-resolution-patterns --clear-criteria
-pm config project get lifecycle-stale-blocker-reason-patterns --json
-```
-
-## Test Result Tracking Policy
-
-`settings.testing.record_results_to_items` controls whether `pm test --run` / `pm test-all` append bounded `test_runs` summaries to item front matter:
-
-- `disabled` (default)
-  - test execution output is returned in command results only
-- `enabled`
-  - successful/failed runs append deterministic item-level `test_runs` summary entries (bounded history retention)
-
-Configure policy with:
-
-```bash
-pm config project set test-result-tracking --policy enabled
-pm config project set test-result-tracking --policy disabled
-pm config project get test-result-tracking --json
-```
-
-## Telemetry Tracking Policy and First-Run Consent
-
-`settings.telemetry.enabled` controls whether command telemetry is exported to the configured ingestion endpoint.
-
-- default: `enabled`
-- opt-out: `disabled`
-- first-run prompt:
-  - interactive TTY only
-  - skipped for non-interactive/CI and JSON-oriented automation paths
-  - persisted in global settings
-
-Configure policy with:
-
-```bash
-pm config global set telemetry-tracking --policy enabled
-pm config global set telemetry-tracking --policy disabled
-pm config global get telemetry-tracking --json
-```
-
-### Telemetry payload version and source context
-
-Command lifecycle telemetry now includes additive payload metadata for segmentation:
-
-- `pm_version` - CLI version resolved at runtime.
-- `source_context` - privacy-safe source bucket (`user`, `automation`, `test`, `dogfood`, `audit_smoke`).
-- `source_context_source` - classification provenance (`inferred` or `env_override`).
-
-Default inference classifies non-interactive/CI/json runs as `automation`, test runtimes as `test`, and interactive sessions as `user`.
-
-For explicit dogfood/audit attribution, override source context with:
-
-```bash
-PM_TELEMETRY_SOURCE_CONTEXT=dogfood pm list-open
-PM_TELEMETRY_SOURCE_CONTEXT=audit_smoke pm context --limit 10
-```
-
-### Optional local OTEL trace export
-
-`pm` can additionally emit one OTLP trace span per command to a local (or custom) collector endpoint:
-
-- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces`
-- or `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318` (auto-appends `/v1/traces`)
-- optional service name override: `OTEL_SERVICE_NAME=pm-cli`
-- disable this OTEL side-channel explicitly with `PM_TELEMETRY_OTEL_DISABLED=1`
-
-Example:
-
-```bash
-OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 OTEL_SERVICE_NAME=pm-cli node dist/cli.js list-open
-```
-
-## Config Discovery and Snapshot Export
-
-`pm config` also supports read-only key discovery and one-shot snapshot export for integration workflows:
-
-```bash
-pm config project list --json
-pm config project export --json
-```
-
-- `list` returns key metadata (`key`, aliases, value kind, applicable set flags, summary) plus current resolved values.
-- `export` returns the resolved config value object in one payload for deterministic machine consumption.
-
-## History Diff and Verify
-
-`pm history` now supports additive diagnostics:
-
-```bash
-# Include changed-field summaries derived from RFC6902 patches
-pm history pm-a1b2 --diff
-
-# Verify before/after hash replay chain and current item hash alignment
-pm history pm-a1b2 --verify --json
-```
-
-`pm restore` also supports history-only recovery when an item file is missing or deleted but its history stream still exists.
-
-## Activity Timeline Filters and Streaming
-
-`pm activity` now supports deterministic timeline slicing plus JSON line streaming for downstream automation:
-
-- Filters: `--id`, `--op`, `--author`, `--from`, `--to`, `--limit`
-- Time bounds accept ISO/date/relative inputs (`--from -7d --to now`, etc.)
-- `--stream` is JSON-only and emits line-delimited payloads (`rows`, `ndjson`, `jsonl`)
-- boolean-style stream enablement is accepted (`--stream`, `--stream true`, `--stream 1`)
-
-```bash
-pm activity --id pm-a1b2 --op update --author codex-agent --from -7d --to now --limit 100
-pm activity --json --stream rows --from -1d --limit 200
-```
-
-## Deadline and Date Inputs
-
-- Date/time inputs used by `--deadline`, `--deadline-before`, `--deadline-after`, calendar `--date/--from/--to`, reminders, and events accept:
-  - ISO timestamps
-  - Flexible date strings (for example `2026-03-31T13-59`, `20260331`, `20260331T135900Z`)
-  - Relative offsets (`+6h`, `+1d`, `+2w`, `+6m`)
-- Accepted values are normalized to canonical ISO timestamps for deterministic storage and filtering.
-- Parse failures now report the precise field context (for example `event.end`, `reminder.at`, `--from`, `deadline-before`) for faster remediation.
-- Compound relative expressions such as `+3d+1h` are rejected; use a single relative token (`+3d`) or an ISO/date string.
-
-## Status Values
-
-- Canonical status values are: `draft`, `open`, `in_progress`, `blocked`, `closed`, `canceled`.
-- Status input flags also accept `in-progress` as an alias for `in_progress` (`pm create`, `pm update`, `pm calendar`, and `pm test-all`).
-- Persisted item data and command output remain canonical (`in_progress`) for deterministic storage and filtering.
-- `pm update --close-reason <text>` sets `close_reason` explicitly; `pm update --unset close-reason` clears it.
-- When `pm update --status` reopens an item from `closed` to a non-terminal status, stale `close_reason` is auto-cleared unless `--close-reason` is explicitly provided in that update call.
-
-Task lifecycle aliases provide discoverable one-step workflows:
-
-- `pm start-task <id>`: claim + move to `in_progress`
-- `pm pause-task <id>`: move to `open` + release claim
-- `pm close-task <id> "<reason>"`: close + release claim metadata
-
-These aliases preserve canonical mutation history entries and accept standard mutation controls (`--author`, `--message`, `--force`; `close-task` also accepts `--validate-close`).
-
-## Resilient Entry Input Formats
-
-Entry-style flags (`--add`, `--remove`, and repeatable create/update seed flags like `--comment`, `--file`, `--test`, `--doc`, `--reminder`, `--event`, `--type-option`) now accept three deterministic forms:
-
-- CSV key/value: `key=value,key2=value2`
-- Markdown-style key/value: `key: value` (single line, bullets, or multiline blocks)
-- Stdin token: pass `-` and pipe payload into the command
-
-Examples:
-
-```bash
-# Files/docs/tests add supports markdown-style key:value
-pm files pm-a1b2 --add "path: src/cli/main.ts,scope: project,note: cli wiring"
-pm docs pm-a1b2 --add $'- path: README.md\n- scope: project\n- note: docs sync'
-pm test pm-a1b2 --add $'command: node scripts/run-tests.mjs test\nscope: project\ntimeout_seconds: 240'
-
-# Linked-path hygiene for files/docs (bulk migrate + optional validation/audit)
-pm files pm-a1b2 --add-glob "src/**/*.ts"
-pm docs pm-a1b2 --add-glob "pattern=docs/**/*.md,scope=project,note=docs sweep"
-pm files pm-a1b2 --migrate "from=src/old/,to=src/new/" --validate-paths --audit
-pm docs pm-a1b2 --migrate "from=docs/legacy/,to=docs/current/" --validate-paths --audit
-pm files pm-a1b2 --add "path=src/new/entry.ts,scope=project" --append-stable
-
-# Discover file paths mentioned in item text before adding them as links
-pm files discover pm-a1b2
-pm files discover pm-a1b2 --apply --note "discovered from item text"
-
-# Comments can be added positionally or with --add
-pm comments pm-a1b2 "captured from shorthand positional text"
-pm comments pm-a1b2 --add "text: captured from markdown formatter"
-pm comments pm-a1b2 --add "handoff note from alternate author" --author "alex-maintainer" --force
-pm comments pm-a1b2 --add "audit note from governance review" --author "audit-maintainer" --allow-audit-comment
-
-# Notes and learnings support the same positional/--add shorthand
-pm notes pm-a1b2 "implementation context captured from shorthand positional text"
-pm notes pm-a1b2 --add "text: parser fallback rationale"
-pm notes pm-a1b2 --add "audit note from governance review" --author "audit-maintainer" --allow-audit-comment
-pm learnings pm-a1b2 --add "text: always run linked tests through the sandbox runner"
-pm learnings pm-a1b2 --add "audit learning from governance review" --author "audit-maintainer" --allow-audit-comment
-
-# CSV-like key fragments remain plain text unless text is explicit
-pm comments pm-a1b2 --add "text=hello,scope:project"          # plain-text fallback
-pm comments pm-a1b2 --add 'text="hello,scope:project"'        # explicit structured text field
-pm notes pm-a1b2 --add "text: hello,scope:project"            # markdown structured form
-
-# Pipe markdown payload via stdin with "-"
-printf '%s\n' 'path: docs/ARCHITECTURE.md' 'scope: project' 'note: piped update' | pm files pm-a1b2 --add -
-printf '%s\n' 'text: evidence from piped stdin' | pm comments pm-a1b2 --add -
-printf '%s\n' 'text: implementation note from piped stdin' | pm notes pm-a1b2 --add -
-printf '%s\n' 'text: learning captured from piped stdin' | pm learnings pm-a1b2 --add -
-printf '%s\n' 'at: +1d' 'text: reminder from piped stdin' | pm update pm-a1b2 --reminder -
-printf '%s\n' 'Backfilled body from stdin token' | pm update pm-a1b2 --body -
-pm update pm-a1b2 --dep "id=pm-b3c4,kind=blocks,author=alex-maintainer,created_at=now"
-pm update pm-a1b2 --dep-remove "pm-b3c4"
-pm update pm-a1b2 --replace-deps --dep "id=pm-c7d8,kind=related,author=alex-maintainer,created_at=now"
-pm update pm-a1b2 --clear-deps
-pm deps pm-a1b2 --format tree
-pm deps pm-a1b2 --format graph --json
-
-# Bulk governance snapshots for latest comments across matching items
-pm comments-audit --status in_progress --parent pm-epic01 --tag governance --latest 1 --limit 20 --json
-
-# Full-history export rows for NDJSON-friendly downstream processing
-pm comments-audit --status in_progress --sprint sprint-12 --release v0.2 --priority 1 --full-history --limit 20 --json
-
-# Summary-only item rows (no comment rows) for scoped inventory checks
-pm comments-audit --status in_progress --latest 0 --limit-items 20 --json
-```
-
-`pm comments-audit --latest` and `--full-history` are intentionally mutually exclusive. `--latest 0` is valid and returns deterministic summary rows with `export.row_count = 0`. `--limit` is an alias for `--limit-items` (both remain supported). All modes now include additive top-level `summary` metrics (`totals`, coverage ratio/percent, and `by_type` breakdown) without changing existing `items`/`filters`/`export` payloads.
-
-Use explicit clear flags for repeatable fields (`--clear-files`, `--clear-comments`, `--clear-docs`, etc.) and `--unset <field>` for scalar clears.
-
-For `pm create` log-seed flags, `--comment` accepts plain-text shorthand (`--comment "triage note"`) in addition to structured forms. Structured `--comment`/`--note`/`--learning` payloads accept only `author`, `created_at`, and `text` keys. Ambiguous unquoted payloads that introduce extra parsed keys (for example `text=hello,scope:project`) are rejected to prevent silent text truncation. Use quoted text (`text="hello,scope:project"`), markdown-style key/value input, or stdin token `-` for punctuation-heavy text.
-
-## Linked Artifact and Test Policy
-
-- Use dedicated linked-artifact commands for file/doc mutations:
-  - `pm files <ID> --add/--add-glob/--remove`
-  - `pm docs <ID> --add/--add-glob/--remove`
-- Use `pm update <ID> --body <value>` to replace an item's body content (including empty-string backfills); use `pm append <ID> --body <value>` for additive narrative updates.
-- Dependency links on existing items are now mutated through `pm update` (`--dep` to add entries, `--clear-deps` to clear all, `--replace-deps` for one-shot atomic replacement, and `--dep-remove`/`--dep_remove` to remove selectors).
-- Use `pm deps <ID> --format tree|graph` for deterministic read-only dependency visualization.
-- `pm update` supports transactional linked mutations in one lock/history operation via repeatable `--comment`, `--note`, `--learning`, `--file`, `--test`, and `--doc` flags.
-- Dedicated commands (`pm comments|notes|learnings|files|test|docs`) remain available for focused single-surface edits.
-- `pm test <ID> --add` intentionally enforces sandbox-safe, runnable command entries. Every new linked test must include `command=...`; optional `path=...` is metadata-only context.
-- `pm create --test` follows the same policy: `command=...` is required, optional `path=...` can annotate command scope.
-- Linked test entries also support optional per-entry runtime directives/assertions plus context override metadata: `env_set=KEY=VALUE;KEY2=VALUE2`, `env_clear=KEY1;KEY2`, `shared_host_safe=true|false`, `pm_context_mode=schema|tracker|auto`, `assert_stdout_contains=...`, `assert_stdout_regex=...`, `assert_stderr_contains=...`, `assert_stderr_regex=...`, `assert_stdout_min_lines=<int>`, `assert_json_field_equals=path=value`, `assert_json_field_gte=path=<number>`.
-- `pm test <ID> --run` / `pm test-all` execute in temporary sandbox roots but seed project/global `settings.json` and `extensions/` directories from source roots so extension-defined type behavior matches direct workspace commands.
-- `pm test <ID> --run` / `pm test-all` support additive run-level runtime controls: repeatable `--env-set KEY=VALUE`, repeatable `--env-clear NAME`, `--shared-host-safe` (ephemeral/shared-host-friendly defaults such as `PORT=0` when unset), `--pm-context schema|tracker|auto`, `--override-linked-pm-context` (force run-level context over per-test `pm_context_mode`), `--check-context`, `--auto-pm-context`, `--fail-on-context-mismatch`, `--fail-on-skipped`, `--fail-on-empty-test-run`, and `--require-assertions-for-pm`.
-- `pm test-all` supports blast-radius pagination with `--limit` and `--offset` before linked-test execution.
-- `pm test <ID> --run --background` and `pm test-all --background` start managed background runs and return run metadata immediately.
-- `pm test-runs` (no subcommand) defaults to `list` output; `pm test-runs list|status|logs|stop|resume` provides explicit background lifecycle management, log tailing, health snapshots, and stop/resume controls.
-- Background run dedupe prevents parallel duplicate execution when an equivalent active run fingerprint already exists.
-- Background run metadata resolves `requested_by` deterministically through: explicit author -> `PM_AUTHOR` -> settings `author_default` -> `USER`/`LOGNAME`/`USERNAME` -> OS username (`whoami`) -> `unknown`.
-- Linked-test `run_results` include `execution_context` metadata (context mode, PM roots, item counts, mismatch signal, extension seeding state, PM tracker-read classification, `requested_pm_context_mode`, and `auto_pm_context_applied`) so PM-command parity is explicit in machine-readable output.
-- With `--check-context`, run warnings include a `context_preflight:...` summary (`checked_pm_commands`, `tracker_read_commands`, `mismatches`, `auto_remediated`) for deterministic diagnostics before/around linked execution.
-- In default `--pm-context schema` mode, PM tracker-read linked commands (for example `list*`, `get`, `search`, `stats`, `test-all`) fail on dataset mismatch by default; use `--pm-context auto` for automatic tracker-read routing or `--pm-context tracker` for full tracker-mode execution.
-- If run-level `--pm-context tracker` is set but a linked test entry pins `pm_context_mode=schema`, mismatch diagnostics explicitly call out per-test override precedence and recommend either changing/removing per-test metadata or passing `--override-linked-pm-context` to force run-level precedence.
-- `pm test <ID> --run` and `pm test-all` emit heartbeat/progress lines to stderr in interactive terminals during long-running linked commands, and support explicit non-interactive progress output via `--progress`.
-- Linked test timeout handling uses deterministic process termination (including force-kill fallback) and reports explicit timeout/maxBuffer diagnostics in `run_results`.
-- Failed linked test `run_results` now include `failure_category` (for example `infra_collision` vs `assertion_failure`) and `pm test-all` totals include aggregated `failure_categories` counts for triage.
-- `pm test <ID> --run` now returns dependency-failed exit code (`5`) when any linked test run result fails (matching `pm test-all` failure gating behavior).
-- `pm list` / `pm list-*` return front-matter rows by default; `pm list` and `pm list-all` also accept `--status <value>` for status-specific filtering without switching subcommands. Pass `--compact` or `--fields <csv>` for projection control, `--sort <field> --order <asc|desc>` for deterministic ordering, `--include-body` when body projection is needed, `--offset <n>` for pagination, and `--stream` (with `--json`) for newline-delimited item streaming.
-
-## Terminal Compatibility
-
-`pm` is intentionally terminal-neutral so it works in native shells, IDE-integrated terminals, and emulated PTY backends:
-
-- Output is plain deterministic TOON/JSON/markdown text (no required terminal-specific OSC/ANSI control protocol).
-- Error exits preserve deterministic exit-code mapping while using graceful `process.exitCode` behavior.
-- Help invocations suppress pager hangs in non-interactive contexts by auto-disabling paging when stdout is not a TTY; use global `--no-pager` for explicit suppression in any context.
-- Stdin token entry (`-`) requires piped stdin when invoked from an interactive TTY.
-- `pm beads import --file -` follows the same stdin guard: if stdin is interactive TTY, `pm` returns usage guidance instead of waiting for EOF.
-- Linked test execution uses shell-compatible spawn orchestration instead of buffered one-shot capture, reducing silent long-run behavior in IDE-integrated terminals.
-- During interactive runs, linked tests print periodic stderr heartbeat lines (`[pm test] linked-test ... running`) until completion.
-- Timeout paths attempt graceful termination first, then deterministic force-kill fallback for stubborn subprocess trees.
-- For manual EOF in interactive sessions:
-  - Unix/macOS terminals: `Ctrl+D`
-  - Windows terminals: `Ctrl+Z` then `Enter`
-
-Example piped Beads import (after installing the bundled extension once per scope):
-
-```bash
-pm extension --install --project beads
-cat issues.jsonl | pm beads import --file -
-```
-
-## Custom Item Types and Type Options
-
-`pm` supports project/global custom item types through `settings.json` and extension registrations. When no custom configuration exists, built-in types keep their default behavior.
-Current built-ins are: `Epic`, `Feature`, `Task`, `Chore`, `Issue`, `Event`, `Reminder`, `Milestone`, and `Meeting`.
-
-### Configure custom types in `settings.json`
-
-```json
-{
-  "item_types": {
-    "definitions": [
-      {
-        "name": "Asset",
-        "folder": "assets",
-        "aliases": ["assets", "3d-asset"],
-        "required_create_fields": ["title", "description", "status", "priority", "message"],
-        "required_create_repeatables": [],
-        "command_option_policies": [
-          { "command": "create", "option": "severity", "enabled": false },
-          { "command": "create", "option": "reporter", "enabled": false },
-          { "command": "create", "option": "goal", "visible": false },
-          { "command": "update", "option": "message", "required": true }
-        ],
-        "options": [
-          {
-            "key": "category",
-            "values": ["Map", "Character", "Prop", "VFX"],
-            "required": true,
-            "aliases": ["asset_category"],
-            "description": "High-level asset classification"
-          },
-          {
-            "key": "pipeline",
-            "values": ["Blockout", "Modeling", "Rigging", "Texturing", "Done"]
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Use custom types on create/update
-
-```bash
-pm create \
-  --title "Forest world map" \
-  --description "Primary world navigation mesh and terrain art" \
-  --type Asset \
-  --status open \
-  --priority 1 \
-  --message "Track world map asset" \
-  --type-option category=Map \
-  --type-option pipeline=Modeling
-
-pm update pm-a1b2 --type-option category=Character --type-option pipeline=Rigging
-```
-
-`--type-option` accepts `key=value`, `key:value`, and `key=<name>,value=<value>` formats (including markdown-style lines), can read stdin via `-`, and can be cleared with `--clear-type-options`.
-
-`command_option_policies` lets each type mark create/update options as:
-
-- `required: true|false` (mandatory or optional)
-- `enabled: true|false` (accepted or rejected at runtime)
-- `visible: true|false` (shown or hidden in policy-aware help guidance)
-
-### Improved required `--type` guidance
-
-When `--type` is missing, usage output now includes:
-
-- why `--type` is required
-- allowed values from the active runtime type registry
-- concrete `pm create` examples (including custom-type usage)
-- deterministic aggregation when multiple required create flags and required `--type-option` keys are missing for the selected type (single response, stable flag ordering)
-- a type-specific "next valid example" command in structured error guidance to accelerate one-shot fixes
-
-For `pm create --help` and `pm update --help`, add `--type <value>` to render type-aware policy details (required/disabled/hidden option lists) and type-option schema details (required marker, allowed values, aliases, description) from active settings/extensions.
-
-## Help and Error Guidance
-
-`pm` now treats command guidance as a first-class UX surface:
-
-- Default help is compact and token-efficient (`Intent` + one high-signal example).
-- Add `--explain` to any `--help` invocation to render deeper rationale, multiple examples, and tips.
-- `pm help` and `pm help <command>` are success paths (exit code `0`) for known command paths; unavailable-command help requests emit explicit `unknown command '<name>'` guidance and return usage exit (`2`).
-- `pm <command> --help --json` and `pm help <command> --json` emit deterministic machine-readable help payloads.
-- Usage/runtime errors use one canonical guidance model:
-  - text mode: structured sections (`What happened`, `What is required`, `Why`, `Examples`, optional `Next steps`)
-  - `--json` mode: machine-readable envelope (`type`, `code`, `title`, `detail`, `required`, `exit_code`, optional `why/examples/next_steps`)
-
-Text-mode example:
-
-```text
-Error: Missing required option --type <value>
-
-What happened:
-  Commander rejected the command because --type <value> was not provided.
-
-What is required:
-  Pass --type <value> with a valid value before running the command.
-```
-
-JSON-mode example (`--json`):
-
-```json
-{
-  "type": "urn:pm-cli:error:missing_required_option",
-  "code": "missing_required_option",
-  "title": "Missing required option --type <value>",
-  "detail": "Commander rejected the command because --type <value> was not provided.",
-  "required": "Pass --type <value> with a valid value before running the command.",
-  "exit_code": 2
-}
-```
-
-## Sparse TOON Default Output
-
-For default TOON output, command results are rendered directly from the command payload with recursive compaction:
-
-- omit `null` and `undefined`
-- omit empty arrays and empty objects
-- preserve meaningful falsy values (`0`, `false`, non-empty strings)
-
-JSON output remains contract-stable and command-contract driven; `pm search` uses compact projection by default unless overridden with `--full` or `--fields`.
-
-## SDK and Full Override Extensions
-
-`pm` now ships a stable SDK entrypoint at `@unbrained/pm-cli/sdk` for extension authors.
-
-```ts
-import { defineExtension, type ExtensionApi } from "@unbrained/pm-cli/sdk";
-
-export default defineExtension({
-  activate(api: ExtensionApi) {
-    api.registerCommand({
-      name: "list-open",
-      run: async (context) => ({ overridden: true, command: context.command }),
-    });
-  },
-});
-```
-
-Extension runtime behavior is extension-first by default:
-
-- Extension command handlers can replace core command execution at dispatch time.
-- Parser overrides (`registerParser`) can rewrite command args/options/global context before dispatch.
-- Preflight overrides (`registerPreflight`) can intercept mutation gate decisions and migration flow.
-- Service overrides (`registerService`) can replace output/error/help rendering and selected internal runtime services.
-- Command-result overrides and renderer overrides still run with deterministic precedence (last registration wins).
-- `beforeCommand` and `afterCommand` hooks receive command args/options/global snapshots and final command result/error state.
-- `registerItemFields(...)` definitions now participate in create/update defaulting and validation.
-- `registerSearchProvider(...)` + `settings.search.provider` and `registerVectorStoreAdapter(...)` + `settings.vector_store.adapter` are now live runtime selectors for `pm search` / `pm reindex`.
-- `registerCommand(...)` definitions can optionally declare action/intent/examples/failure hints/arguments/flags metadata, which is surfaced in dynamic `--help` text, `--help --json` payloads, and `pm contracts`.
-
-Use `--no-extensions` to force core-only behavior for a single invocation.
-
-## Extension Lifecycle Manager (`pm extension`)
-
-Use `pm extension` to install, adopt, inspect, manage, activate, deactivate, and remove custom extensions in project or global scope.
-
-Lifecycle actions (exactly one per call):
-
-- `--init` (alias: `--scaffold`)
-- `--install`
-- `--uninstall`
-- `--explore`
-- `--manage`
-- `--doctor`
-- `--adopt`
-- `--adopt-all`
-- `--activate`
-- `--deactivate`
-
-Scope selectors:
-
-- `--project` (default)
-- `--local` (alias of `--project`)
-- `--global`
-
-Install source selectors:
-
-- local extension directory path (for example `.agents/pm/extensions/my-ext`)
-- GitHub URL (for example `https://github.com/owner/repo/tree/main/path/to/ext`)
-- GitHub shorthand URL form (for example `github.com/owner/repo/path`)
-- explicit GitHub shorthand flag form `--gh owner/repo/path` (alias: `--github`)
-- optional Git ref override with `--ref <branch|tag|sha>`
-
-Requested source equivalence examples:
-
-```bash
-# Scaffold a starter extension project (manifest + entrypoint + README)
-pm extension --init ./my-extension
-pm extension scaffold ./my-extension
-
-# Bundled managed aliases shipped with pm-cli (not auto-installed)
-pm extension --install --project beads
-pm extension --install --project todos
-
-# Equivalent explicit local bundled paths
-pm extension --install --project .agents/pm/extensions/beads
-pm extension --install --project .agents/pm/extensions/todos
-
-# Custom extension roots in repo
-pm extension --install --project https://github.com/unbraind/pm-cli/tree/main/.custom/pm-extensions/my-ext
-pm extension --install --project github.com/unbraind/pm-cli/.custom/pm-extensions/my-ext
-pm extension --install --project --gh unbraind/pm-cli/.custom/pm-extensions/my-ext
-
-# Single-extension repo or extension at repository root
-pm extension --install --project https://github.com/unbraind/pm-cli
-pm extension --install --project github.com/unbraind/pm-cli
-pm extension --install --project --gh unbraind/pm-cli
-```
-
-Canonical public shorthand examples in this repository use `unbraind/pm-cli`. For private repositories, ensure your git credentials can access the source before using `--gh` or `github.com/...` selectors.
-
-Activation and health behavior:
-
-- `pm extension --init`/`--scaffold` creates an idempotent starter extension scaffold (manifest, entrypoint, README) and reports deterministic next steps.
-- Install auto-activates the extension in selected scope settings.
-- Deactivate/activate toggle `extensions.disabled[]`/`extensions.enabled[]` in settings.
-- `pm extension --explore` lists discovered extensions and compatibility/runtime status fields (`active` compatibility alias, `enabled`, `runtime_active`, `activation_status`).
-- `pm extension --adopt` records an existing unmanaged extension into managed state (local or GitHub provenance metadata) without reinstalling extension files.
-- `pm extension --adopt-all` bulk-adopts all unmanaged extensions in the selected scope without reinstalling files.
-- `pm extension --manage` refreshes GitHub-managed update metadata, persists it to scope-local `.managed-extensions.json`, and includes explicit per-extension `update_check_status`/`update_check_reason` fields (`checked`, `failed`, `skipped_unmanaged`, `skipped_non_github`, `not_checked`) plus triage status totals/remediation hints and update-health coverage diagnostics (`update_health_coverage`, `warning_codes`). `--runtime-probe` opt-in runs doctor-equivalent runtime activation checks for manage output parity. `--fix-managed-state` can adopt unmanaged extensions before update checks.
-- `pm extension --doctor` (or `pm extension doctor`) provides consolidated extension diagnostics with normalized warning codes, canonical load roots, active-vs-loaded consistency diagnostics, update-health coverage signals, remediation hints, optional strict exit gating (`--strict-exit`, alias `--fail-on-warn`), machine-usable blocking indicators (`blocking_failure_count`, `has_blocking_failures`), and optional deep output via `--detail deep`. `--trace` (deep mode) includes actionable registration traces and expected-schema hints for activation failures. `--fix-managed-state` can adopt unmanaged extensions before diagnostics.
-- Doctor load diagnostics include targeted guidance codes for common local setup failures: `extension_load_failed_sdk_dependency_missing` (missing `@unbrained/pm-cli` dependency) and `extension_load_failed_module_mode_mismatch` (ESM entry without `"type": "module"` or `.mjs` mode alignment).
-- Subcommand invocation forms (`pm extension manage ...`, `pm extension doctor ...`) honor the same action flags (`--runtime-probe`, `--detail`, `--trace`, etc.) as top-level action-flag forms.
-- `pm health` includes managed extension state diagnostics plus a condensed extension triage block for quick load/activation/migration issue triage across project/global roots, including `extension_update_health_partial_coverage` only when unmanaged loaded extensions are action-required for update-check coverage.
-- Unknown manifest capabilities emit `extension_capability_unknown` diagnostics with inline allowed-capability lists, nearest-match suggestions, and legacy alias guidance (`migration`/`validation` -> `schema`). Health/doctor payloads include machine-readable capability contract metadata (`details.capability_contract`) and parsed guidance entries (`details.capability_guidance`).
-- Legacy extension command definitions using `handler` remain compatible and map to `run`, with deterministic warning `extension_command_definition_legacy_handler_alias` for migration visibility.
-
-Use `pm extension --help` for compact guidance or `pm extension --help --explain` for expanded examples/tips.
-
-## Calendar, Reminders, and Events
-
-`pm` supports persistent reminder metadata, one-off and recurring scheduled events, and a dedicated calendar surface for deadline/reminder/event planning.
-
-### Reminder fields on items
-
-- `pm create` and `pm update` accept repeatable `--reminder` flags.
-- Reminder value format: `at=<iso|date|relative>,text=<text>`.
-- Use `--clear-reminders` to clear reminders on create/update.
-
-Examples:
-
-```bash
-pm create \
-  --title "Prepare release notes" \
-  --description "Draft and review release notes for vnext." \
-  --create-mode progressive \
-  --type Task \
-  --status open \
-  --priority 1 \
-  --tags "release,docs" \
-  --body "" \
-  --deadline +2d \
-  --reminder "at=+1d,text=Start first draft" \
-  --reminder "at=+36h,text=Send review draft" \
-  --estimate 45 \
-  --acceptance-criteria "Release notes merged and linked." \
-  --author "maintainer-agent" \
-  --message "Create release notes task with reminders"
-
-pm update pm-a1b2 --reminder "at=+4h,text=Follow up with reviewer"
-pm update pm-a1b2 --clear-reminders
-```
-
-### Event fields on items
-
-- `pm create` and `pm update` accept repeatable `--event` flags.
-- Event value format supports:
-  - `start=<iso|date|relative>` (required)
-  - `end=<iso|date|relative>` (optional, must be after `start`)
-  - `title=<text>`, `description=<text>`, `location=<text>`, `timezone=<iana-or-label>`, `all_day=<true|false|1|0|yes|no>`
-- Recurrence metadata (optional, RFC-lite):
-  - `recur_freq=<daily|weekly|monthly|yearly>`
-  - `recur_interval=<int>=1+`
-  - `recur_count=<int>=1+`
-  - `recur_until=<iso|date|relative>`
-  - `recur_by_weekday=<mon|tue|wed|thu|fri|sat|sun>` (pipe-delimited)
-  - `recur_by_month_day=<1..31>` (pipe-delimited)
-  - `recur_exdates=<iso|date|relative>` (pipe-delimited)
-- Use `--clear-events` to clear all events in create/update flows.
-
-Examples:
-
-```bash
-pm create \
-  --title "Run release planning" \
-  --description "Set recurring planning sync plus a one-off launch checkpoint." \
-  --create-mode progressive \
-  --type Task \
-  --status open \
-  --priority 1 \
-  --tags "release,calendar" \
-  --body "" \
-  --deadline +7d \
-  --event "start=2026-04-03T15:00:00.000Z,title=Launch checkpoint,location=War room" \
-  --event "start=2026-04-01T09:00:00.000Z,title=Weekly planning,recur_freq=weekly,recur_by_weekday=wed,recur_interval=1" \
-  --estimate 30 \
-  --acceptance-criteria "Calendar schedule is captured in item metadata." \
-  --author "maintainer-agent" \
-  --message "Create calendar-rich planning task"
-
-pm update pm-a1b2 --event "start=+2d,title=Retro,recur_freq=monthly,recur_by_month_day=15"
-pm update pm-a1b2 --clear-events
-```
-
-### Calendar command (`pm calendar` / `pm cal`)
-
-- Views: `agenda` (default), `day`, `week`, `month`
-- Default output for calendar is markdown (command-specific override)
-- Explicit output override: `--format markdown|toon|json` or global `--json`
-- JSON summary includes deterministic aggregate breakdowns: `by_kind`, `by_type`, `by_status`, and `recurring_events`.
-- Markdown event lines include richer deterministic metadata for agent parsing (item type, event title, recurrence marker/rule, end-time, timezone, location, and description when present).
-- Event source controls:
-  - `--include deadlines|reminders|events|all` (comma or pipe-delimited when passing multiple values)
-  - default source set is `all`
-- Recurrence expansion controls:
-  - `--recurrence-lookahead-days <n>`
-  - `--recurrence-lookback-days <n>`
-  - `--occurrence-limit <n>` (per recurring event; `>= 1`)
-- Past toggles and range controls:
-  - `--past` includes past events in bounded views
-  - `--full-period` keeps day/week/month windows anchored to full period boundaries (without now-clipping)
-  - `--from` / `--to` supported on `agenda` (accept `today` as a day-start alias)
-  - `--date` anchors day/week/month calculations (accepts `today` as a day-start alias)
-- Shared filters: `--type`, `--tag`, `--priority`, `--status`, `--assignee`, `--assignee-filter assigned|unassigned`, `--sprint`, `--release`, `--limit`
-
-Examples:
-
-```bash
-pm calendar
-pm calendar --view day --date today --past
-pm cal --view week --date +2d --past
-pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events
-pm calendar --view agenda --from 2026-04-01T00:00:00.000Z --to 2026-04-08T00:00:00.000Z --assignee alex
-pm calendar --view agenda --include events --recurrence-lookahead-days 30 --occurrence-limit 50
-pm calendar --view month --tag release --format json
-```
-
-## Context Snapshot (`pm context` / `pm ctx`)
-
-`pm context` provides a token-efficient project-state snapshot optimized for quickly deciding the next work item.
-
-- Default output is TOON (sparse and agent-friendly), with explicit `--format markdown|toon|json` and global `--json`.
-- Focus sections prioritize active work (`in_progress`, then `open`) using deterministic ranking:
-  - status
-  - priority (`0..4`, lower is higher priority)
-  - explicit `order` (when present)
-  - deadline proximity
-  - recency/id tie-breakers
-- Output is split into:
-  - high-level focus (`Epic`, `Feature`)
-  - low-level focus (`Task`, `Issue`, `Chore`, `Event`, `Reminder`, `Milestone`, `Meeting`, etc.)
-- Agenda context is included from deadlines, reminders, and scheduled events in an agenda window.
-- If there are no open or in-progress items, `pm context` automatically includes a blocked-work fallback section.
-- Shared filters: `--type`, `--tag`, `--priority`, `--assignee`, `--sprint`, `--release`, `--limit`.
-- Agenda window controls: `--date`, `--from`, `--to`, `--past`.
-
-Examples:
-
-```bash
-pm context
-pm ctx --limit 5
-pm context --assignee alex --priority 1 --limit 10
-pm context --from +0d --to +7d --format markdown
-pm context --date 2026-04-01T00:00:00.000Z --past --json
-```
+Docs should link to relevant `pm` items, and `pm` items should link back to changed docs through `pm docs`.
 
-## Documentation
+## Privacy Boundary
 
-- [Architecture](docs/ARCHITECTURE.md)
-- [SDK Guide](docs/SDK.md)
-- [Telemetry and GDPR Operations](docs/TELEMETRY.md)
-- [Remote Telemetry Stack Runbook](docs/operations/REMOTE_TELEMETRY_STACK.md)
-- [Extensions](docs/EXTENSIONS.md)
-- [Contributing](CONTRIBUTING.md)
-- [Security Policy](SECURITY.md)
-- [Changelog](CHANGELOG.md)
+Private production operations material is local-only, gitignored, and intentionally not linked from public documentation or packaged release files. Keep public docs focused on user-facing CLI behavior and safe contribution workflows.
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+[MIT](LICENSE)