@unbrained/pm-cli 2026.6.5 → 2026.6.6

package/docs/AGENT_GUIDE.md

@@ -19,7 +19,7 @@ pm guide workflows
 If a relevant item exists, reuse it. If not, create a parent lineage, then create and claim the child implementation item.
 When AGENTS/CLAUDE guidance is missing, use `pm init --agent-guidance add` to inject compact workflow guardrails, or `pm init --agent-guidance skip` to persist an explicit decline.
 
-Tracked documentation work: [pm-3042](../.agents/pm/epics/pm-3042.toon), [pm-r9gu](../.agents/pm/features/pm-r9gu.toon), [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Canonical Loop
 

package/docs/ARCHITECTURE.md

@@ -10,7 +10,7 @@ This page is for contributors changing `pm-cli` internals. Users should start wi
 - Items are stored as TOON by default; history is append-only JSONL.
 - `pm contracts` is the machine-readable runtime contract source.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## System Overview
 
@@ -205,6 +205,16 @@ pm contracts --command create --flags-only --json
 pm help create --json
 ```
 
+## Telemetry Schema Negotiation
+
+Telemetry preserves wire compatibility through an explicit client/server negotiation split:
+
+- Event payloads keep `event.schema_version` as the event-document schema (currently v1).
+- Queue envelopes include `client_schema_version` so client/runtime evolution can be tracked independently from event payload versioning.
+- `pm health --check-telemetry` probes `/healthz` and records any advertised max-version header for observability/debugging.
+
+This keeps v1 behavior stable while providing a forward path for future telemetry schema upgrades.
+
 ## Output Pipeline
 
 Core output formats:

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -65,7 +65,7 @@ This clones the repo, reads `.claude-plugin/marketplace.json` at the root, insta
 claude mcp add --transport stdio pm-mcp -- npx -y @unbrained/pm-cli pm-mcp
 ```
 
-Gives you the 18 MCP tools without skills or slash commands.
+Gives you the 21 MCP tools without skills or slash commands.
 
 ### 3. Direct project `.mcp.json` (project-scoped MCP only)
 
@@ -123,7 +123,7 @@ node scripts/smoke-claude-plugin.mjs
 pnpm smoke:claude-plugin
 ```
 
-Verifies: plugin file structure, manifest name consistency, MCP initialize, 18 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
+Verifies: plugin file structure, manifest name consistency, MCP initialize, 21 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
 
 ### MCP server smoke test
 

package/docs/COMMANDS.md

@@ -16,13 +16,13 @@ pm contracts --command <command> --flags-only --json
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Command Families
 
 | Family | Commands | Purpose |
 |--------|----------|---------|
-| Bootstrap | `init`, `config`, `health` | create and inspect tracker setup |
+| Bootstrap | `init`, `config`, `health`, `telemetry` | create and inspect tracker setup |
 | Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit` | find work and audit decomposition |
 | Lifecycle | `create`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state |
 | 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 |
@@ -44,6 +44,7 @@ pm init --agent-guidance status
 pm init --agent-guidance add
 pm config project list
 pm health --check-only --summary --json
+pm telemetry status
 ```
 
 `pm init` creates `.agents/pm`. `pm health --check-only --summary --json` gives the smallest machine-readable health gate without refreshing optional search artifacts.
@@ -303,12 +304,31 @@ pm validate --check-files --scan-mode tracked-all
 pm validate --check-resolution --fix-hints --json
 pm normalize --dry-run --json
 pm gc --dry-run
+pm gc --scope locks --dry-run
 ```
 
 Use dry-run modes before broad lifecycle or cleanup changes.
 
+`pm gc` accepts `--scope` values `index`, `embeddings`, `runtime`, and `locks` (comma-separated or repeatable); with no `--scope` it sweeps all of them. The `locks` scope removes only **expired** lock files in `locks/` — those whose own embedded `created_at + ttl_seconds` has elapsed (debris left by crashed processes). Active locks and any lock file that cannot be parsed are always retained (never deleted when staleness cannot be proven), and the result includes a `locks` summary (`scanned`/`removed`/`retained`).
+
 `--fix-hints` is a read-only flag: each failing check gains `details.fix_hints`, an array of `pm` command templates derived from the warning codes it raised (for example `pm history-repair <id>` for history drift, or `pm update <id> --reviewer "<name>"` for a missing reviewer). Generic hints may contain `<id>`/`<field>`/`<path>` placeholders the agent substitutes from the check's detail rows; the resolution check aliases concrete per-row commands and marks `fix_hints_truncated` when the list is summarized. It never mutates items. The mapping comes from the shared remediation registry that also backs `pm health --json` (see Self-Repair Remediation below), so agents gating on `pm validate` can auto-repair findings without hardcoding warning-code-to-command lookups.
 
+### Telemetry Local Analytics
+
+`pm telemetry` surfaces local queue/runtime telemetry state without running full health checks:
+
+```bash
+pm telemetry status
+pm telemetry stats --limit 10
+pm telemetry flush
+pm telemetry clear
+```
+
+- `status` reports queue depth, endpoint, and latest flush metadata.
+- `stats` groups queued local telemetry events by command name.
+- `flush` runs an immediate local queue flush attempt.
+- `clear` disables telemetry and deletes local queue/runtime telemetry artifacts.
+
 ### Self-Repair Remediation
 
 `pm health --json` annotates every non-extension check whose warnings have a known code with `details.remediation_map`, an object mapping each warning-code prefix to the executable `pm` command that fixes it:
@@ -326,6 +346,8 @@ Use dry-run modes before broad lifecycle or cleanup changes.
 
 ```bash
 pm history <id> --limit 20
+pm history <id> --diff
+pm history <id> --diff --field status
 pm history <id> --full --diff --verify
 pm history-redact <id> --literal "[redacted_path_prefix]/private" --replacement "[redacted_path]"
 pm history-redact <id> --regex "/192\\.168\\.[0-9.]+/g" --dry-run
@@ -337,6 +359,15 @@ pm restore <id> <timestamp-or-version>
 ```
 
 History is append-only. Restore appends a new restore event instead of rewriting old history.
+
+`--diff` replays the history chain and emits, per entry, a `changes` array of `{ field, before, after }` field-level value transitions (alongside the `changed_fields` name list) — so you can see exactly what each field changed from and to without comparing snapshots. It is independent of the compact/full projection. `--field <name>` narrows the diff to a single field's transitions (implying `--diff`), answering "when did `<field>` change?" — e.g. `pm history <id> --diff --field status`.
+
+`pm stats` reports item and history totals plus per-type/per-status counts. Add `--storage` for aggregate history-stream metrics — `total_streams`, `total_lines`, `total_bytes`, the top streams by size (`largest_by_bytes`) and by depth (`deepest_by_lines`), and the global `oldest_entry`/`newest_entry` — to decide when to compact or redact streams and to plan storage:
+
+```bash
+pm stats
+pm stats --storage --json
+```
 `history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied.
 `history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream.
 

package/docs/CONFIGURATION.md

@@ -9,7 +9,7 @@
 - Use `--json` only when strict parsing is needed.
 - Use `pm contracts` for current command/schema metadata.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon), [pm-1lkm](../.agents/pm/features/pm-1lkm.toon), [pm-qq69](../.agents/pm/features/pm-qq69.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Configuration Commands
 
@@ -177,6 +177,14 @@ Keyword search is always available:
 pm search "release docs" --mode keyword --limit 10
 ```
 
+`search.tuning` controls deterministic lexical weighting in keyword mode and the lexical component of hybrid mode. Default runtime weights:
+
+- `title_exact_bonus=10`
+- `title_weight=8`, `description_weight=5`, `tags_weight=6`, `status_weight=2`
+- `body_weight=1`, `comments_weight=1`, `notes_weight=1`, `learnings_weight=1`
+- `reminders_weight=2`, `events_weight=2`
+- `dependencies_weight=3`, `linked_content_weight=1`
+
 Semantic and hybrid search can use built-in OpenAI-compatible or Ollama providers plus vector stores such as Qdrant or LanceDB. If local Ollama is available and semantic settings are unset, `pm` can resolve local defaults automatically.
 
 For local Ollama or slower embedding providers, tune `search.embedding_batch_size`, `search.embedding_timeout_ms`, and `search.scanner_max_batch_retries` in project config before assuming semantic search is broken. Keyword search remains the fast baseline while semantic indexing catches up.

package/docs/EXTENSIONS.md

@@ -18,6 +18,7 @@ Related docs:
 - [Configuration](CONFIGURATION.md)
 - [Testing](TESTING.md)
 - [Command Reference](COMMANDS.md)
+- [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md)
 
 ## Package Sources
 
@@ -310,6 +311,12 @@ pm contracts --runtime-only --schema-only --json
 pm contracts --command <command> --flags-only --json
 ```
 
+Detailed package-author runtime contracts live in
+[Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md), including
+`telemetry.capture_level`, create-path vs `mutateItem` write behavior, and hook
+surface guarantees.
+
+
 ## Lifecycle Commands
 
 Explore installed runtime entries:

package/docs/EXTENSION_AUTHOR_CONTRACTS.md

@@ -0,0 +1,73 @@
+# Extension Author Contracts
+
+Tracker: pm-at83
+
+This page records runtime contracts package authors need when they build on the public SDK. For the install, manifest, lifecycle, and troubleshooting overview, see [Packages and Extensions](EXTENSIONS.md).
+
+## Telemetry Capture Level
+
+Every `pm` command records a telemetry event. Extension commands use the same telemetry pipeline as core commands and inherit `telemetry.capture_level` from the active settings.
+
+Allowed values:
+
+| Value | Meaning |
+|-------|---------|
+| `redacted` | Default. Records sanitized command args, options, result summary, and runtime environment. |
+| `minimal` | Records structural metadata and one-way digests only. No readable command text, args, options, result summary, or runtime environment is kept. |
+| `max` | Same as `redacted`, but raises the per-string truncation cap from 512 to 2048 characters. Redaction still applies. |
+
+All levels redact inline secrets, bearer tokens, private paths, emails, private IPv4 addresses, and object keys whose names look sensitive. `minimal` additionally digests arg and option values with HMAC-SHA-256 so extension authors cannot reconstruct user input.
+
+Inspect and change the level:
+
+```bash
+pm health --json | jq '.details.capture_level'
+pm config set telemetry.capture_level minimal
+pm config set telemetry.capture_level redacted
+pm config set telemetry.capture_level max
+```
+
+The setting lives in the global pm settings file (`~/.pm-cli/settings.json` by default), not in the project tracker.
+
+## Item Write Paths
+
+`pm` has two item write paths. Hook, service, and migration authors should treat them as different contracts.
+
+Create path:
+
+- Used by `pm create` and importer-created items.
+- Acquires the item lock, writes the item file atomically, appends the create history entry, fires `onWrite` for the item file and history stream, records the after-command affected-item snapshot, then releases the lock.
+- Does not fire `onRead`, because there is no existing item.
+- Does not call the `item_store_write` service override. Use `onWrite` with `op="create"` if a package needs to observe new items.
+
+`mutateItem` path:
+
+- Used by `pm update`, `pm close`, `pm claim`, `pm release`, `pm restore`, `pm delete`, and other mutations of existing items.
+- Locates the item, acquires the lock, reads the item through the `onRead` hook, enforces ownership and history policy, applies the mutation, consults `item_store_write`, writes the item atomically, appends history, fires `onWrite` for the item and history stream, records the after-command affected-item snapshot, then releases the lock.
+- `item_store_write` handlers can redirect the target path, replace serialized contents, or skip the physical item write.
+
+Both paths guarantee:
+
+- Atomic item writes.
+- Lock coverage across item write and history append.
+- History append after the item write, with rollback if history append fails.
+- `onWrite` hooks only after item and history commits.
+- Non-fatal hook failures reported as `extension_hook_failed:<layer>:<name>:onWrite`.
+
+`changed_fields` sentinel values:
+
+| Value | Meaning |
+|-------|---------|
+| `["imported"]` | Item came from an importer. |
+| `["restored"]` | Item was restored from a previous state. |
+| `["deleted"]` | Item was deleted. |
+
+Surface matrix:
+
+| Surface | Create path | `mutateItem` path |
+|---------|-------------|-------------------|
+| `onRead` hook | No | Yes |
+| `item_store_write` service override | No | Yes |
+| `history_append` service override | Yes | Yes |
+| `onWrite` item hook | Yes, `op="create"` | Yes, `op=<mutation op>` |
+| `onWrite` history hook | Yes, `op="create:history"` | Yes, `op="<mutation op>:history"` |

package/docs/ONBOARDING.md

@@ -0,0 +1,165 @@
+# Onboarding
+
+Use this guide to become productive in your first two hours without breaking release flow or tracker integrity.
+
+## Agent Quick Context
+
+- Bootstrap with `npm install -g .`, verify toolchain versions, then run `pnpm build`.
+- Use `pm context` + `pm search` before creating any new item.
+- Claim before substantial edits and link files/docs/tests as you go.
+- Run sandbox-safe tests before closing items.
+- Never hand-edit tracker records or generated changelog output.
+
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon), [pm-oh5h](../.agents/pm/tasks/pm-oh5h.toon), [pm-10ml](../.agents/pm/stories/pm-10ml.toon).
+
+## Prerequisites
+
+- Node.js 20 or newer
+- pnpm 10 or newer
+- Git + GitHub CLI (`gh`) authenticated for this repository
+
+## First-Time Bootstrap (Real Repository Work)
+
+Run from the repository root:
+
+```bash
+npm install -g .
+pm --version
+node -v
+pnpm -v
+pnpm build
+export PM_AUTHOR="<stable-agent-id>"
+```
+
+For real repository tracking, do not set `PM_PATH`.
+
+## First Read Path
+
+Use progressive disclosure:
+
+```bash
+pm context --limit 10
+pm search "<request keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+pm install guide-shell --project
+pm guide workflows
+```
+
+Then use:
+
+- [Agent Guide](AGENT_GUIDE.md)
+- [Command Reference](COMMANDS.md)
+- [Testing](TESTING.md)
+- [Releasing](RELEASING.md)
+
+## Safe Local Verification
+
+Use sandbox-safe wrappers for test execution:
+
+```bash
+node scripts/run-tests.mjs test
+node scripts/run-tests.mjs coverage
+```
+
+Standard local gate set:
+
+```bash
+pnpm build
+pnpm typecheck
+node scripts/run-tests.mjs coverage
+pnpm quality:docs-skills
+pm validate --check-resolution --check-history-drift
+```
+
+## Real Tracker Workflow (Canonical Loop)
+
+1) Orient and dedupe
+
+```bash
+pm context --limit 10
+pm search "<keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+2) Claim and start
+
+```bash
+pm claim <id>
+pm update <id> --status in_progress --message "Start implementation"
+```
+
+3) Link execution context while editing
+
+```bash
+pm files <id> --add path=src/...,scope=project,note="implementation scope"
+pm docs <id> --add path=docs/...,scope=project,note="user-facing behavior"
+pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/...",scope=project,timeout_seconds=240
+```
+
+4) Record progress
+
+```bash
+pm comments <id> "Progress update and rationale."
+pm notes <id> --add "Design tradeoff."
+pm learnings <id> --add "Durable lesson."
+```
+
+5) Verify, close, and release
+
+```bash
+pm test <id> --run --progress
+pm comments <id> "Evidence: linked tests and gates passed."
+pm close <id> "Acceptance criteria met; verification passed." --validate-close warn
+pm release <id>
+```
+
+## Release Overview
+
+- Daily release prep runs via `.github/workflows/auto-release.yml`.
+- Tag-triggered publish runs via `.github/workflows/release.yml`.
+- `CHANGELOG.md` is generated by `pm-changelog` and must stay package-generated.
+
+Local parity:
+
+```bash
+pnpm release:pipeline:dry-run
+pnpm release:pipeline
+```
+
+## Hard Never-Do List
+
+- Do not hand-edit `CHANGELOG.md` (use `pnpm changelog:pm` only).
+- Do not run manual `npm publish` for this project.
+- Do not set `PM_PATH` for real repository mutations.
+- Do not edit `.agents/pm/**` files directly; mutate through `pm` commands.
+- Do not bypass governance with destructive git commands unless explicitly approved.
+
+## Diagnostics and Recovery
+
+```bash
+pm health --check-only
+pm validate --check-resolution --check-history-drift
+pm normalize --dry-run --json
+pm package doctor --project --detail summary
+pm contracts --command <command> --flags-only --json
+```
+
+If history drift is reported:
+
+```bash
+pm history-repair <id> --dry-run
+pm history-repair <id>
+```
+
+If sensitive content is found in history:
+
+```bash
+pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run
+pm history-redact <id> --literal "<secret>" --replacement "[redacted]"
+```
+
+## Private Operations Boundary
+
+Keep credentials, host-specific runbooks, internal topology, and raw private reliability logs out of tracked docs and package output. Keep those details in local, ignored operations notes.

package/docs/QUICKSTART.md

@@ -11,7 +11,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Close only after evidence is recorded.
 - Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Install
 

package/docs/README.md

@@ -20,15 +20,18 @@ pm guide release --json
 | Reader | First page | Then read |
 |--------|------------|-----------|
 | New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
+| New maintainer | [Onboarding](ONBOARDING.md) | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md) |
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
+| Claude Code user | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
 - [Quickstart](QUICKSTART.md) - install, initialize, create, claim, link, test, close.
+- [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
@@ -37,6 +40,7 @@ pm guide release --json
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
+- [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) - native Claude Code plugin architecture and install flow.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
 
@@ -71,11 +75,15 @@ Community files:
 
 ## Tracker References
 
-This documentation structure is tracked through:
+Current documentation structure work is tracked through:
 
-- [pm-3042](../.agents/pm/epics/pm-3042.toon)
-- [pm-r9gu](../.agents/pm/features/pm-r9gu.toon)
-- [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon)
+- [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon)
+
+Legacy documentation baseline references (closed):
+
+- [pm-3042](../.agents/pm/epics/pm-3042.toon) (closed)
+- [pm-r9gu](../.agents/pm/features/pm-r9gu.toon) (closed)
+- [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon) (closed)
 
 When changing docs, link files back to the active item:
 

package/docs/RELEASING.md

@@ -12,7 +12,7 @@ For local progressive-disclosure routing, install `guide-shell` with `pm install
 - Run local parity gates before pushing release tags.
 - Use `pm guide release --json` for machine-readable release docs routing after `guide-shell` is installed.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Version Policy
 
@@ -74,6 +74,41 @@ The pipeline performs:
 
 The generated changelog includes clickable pm item links to the tracked `.toon` files. Missing release evidence should be fixed in pm item history, not by hand-editing `CHANGELOG.md`.
 
+## Changelog Classification (Contributor-Facing)
+
+`pnpm changelog:pm` routes closed pm items into keep-a-changelog sections using `pm-changelog` classification logic. Use explicit type/tag metadata when you want deterministic section routing.
+
+Signal tiers:
+
+- **Strong signals**: item `type` + `tags`
+- **Weak signal**: item `title` (after stripping CLI-flag-like tokens such as `--add`)
+
+Category precedence (first matching bucket wins):
+
+| Priority | Category | Trigger terms (from strong + weak signals unless noted) |
+|---|---|---|
+| 1 | `Security` | `security`, `cve`, `vulnerability` |
+| 2 | `Deprecated` | `deprecated`, `deprecation` |
+| 3 | `Removed` | `removed`, `remove`, `deleted`, `delete` |
+| 4 | `Fixed` | `fix`, `fixed`, `bug`, `bugfix`, `hotfix`, `regression` |
+| 5 | `Added` | `feature`, `feat`, `added`, `add`, `new` |
+| 6 | `Changed` | strong-signal `change`, `changed`, `refactor`, `update`, `updated`, `improve`; for non-bug-like types only, title fallback is also used |
+| 7 | `Other` | no classifier match |
+
+Bug-like default:
+
+- Items with type `Issue`, `Bug`, `Bugfix`, or `Defect` default to `Fixed` unless a higher-priority category already matched.
+- This bug-like default runs before title-only `Changed` fallback to avoid misrouting command-name issue titles (for example "`pm update ...`" issue reports).
+
+Practical examples:
+
+- `Issue` + title `pm update --add-tags fails` -> `Fixed`
+- `Task` + tag `refactor` -> `Changed`
+- `Feature` + tag `security` -> `Security`
+- `Issue` + tag `feature` -> `Added` (explicit stronger signal beats default)
+
+If a changelog routing rule appears incorrect, fix classifier behavior in the `pm-changelog` package/repo and then consume the updated package here. Do not patch generator internals in this repository.
+
 ## Local Release Parity Checklist
 
 1. Confirm or compute the version.

package/docs/TESTING.md

@@ -9,7 +9,7 @@ This page describes safe local tests, linked tests, coverage, and release-readin
 - Linked tests added through `pm test` should use sandbox-safe commands.
 - Run linked tests before closing the item that owns the work.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Standard Local Checks
 
@@ -140,3 +140,21 @@ rg -n "forbidden-private-token-or-path" README.md docs
 ```
 
 Replace the placeholder pattern with the actual sensitive term being guarded in the current task.
+
+## Contract Snapshot Gate
+
+Tracked by [pm-d6kq](../.agents/pm/tasks/pm-d6kq.toon).
+
+`pm contracts --full --json` is a public machine-readable SDK and agent surface.
+Keep its committed golden snapshot current when command contracts, schemas,
+aliases, or extension-provided command contracts intentionally change:
+
+```bash
+pnpm build
+pnpm contracts:update
+pnpm contracts:check
+```
+
+CI runs `pnpm contracts:check` in the static gate. Snapshot diffs should be
+reviewed like an API change and paired with the package-owned changelog flow
+when the contract surface changes intentionally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.5",
+  "version": "2026.6.6",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -74,6 +74,9 @@
     "test:coverage": "node scripts/run-tests.mjs coverage",
     "quality:static": "node scripts/release/static-quality-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
+    "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
+    "contracts:update": "node scripts/contracts-snapshot.mjs --update",
+    "contracts:check": "node scripts/contracts-snapshot.mjs --check",
     "dogfood:package-first": "node scripts/dogfood-package-first.mjs",
     "smoke:external-packages": "node scripts/smoke-external-packages.mjs",
     "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
@@ -129,7 +132,7 @@
   },
   "devDependencies": {
     "@sentry/cli": "^3.5.0",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "0.28.0",
     "tsx": "^4.22.4",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-claude",
-  "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents (coordinator, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
+  "description": "Native pm CLI integration for Claude Code — 21 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents (coordinator, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
   "version": "1.4.0",
   "author": {
     "name": "unbrained",

package/plugins/pm-claude/README.md

@@ -6,7 +6,7 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 
 | Component | What it provides |
 |-----------|----------------|
-| **18 MCP tools** | Full pm surface: context, search, list, get, create, update, claim, release, close, comments, files, docs, test, validate, health, contracts, plan + `pm_run` for everything else |
+| **21 MCP tools** | Full pm surface: context, search, list, get, create, update, claim, release, close, comments, files, docs, notes, learnings, deps, test, validate, health, contracts, plan + `pm_run` for everything else |
 | **5 skills** | `pm-workflow`, `pm-developer`, `pm-release`, `pm-audit`, `pm-planner` — auto-loaded as Claude Code skills |
 | **14 slash commands** | Full lifecycle coverage — status, start, close, triage, audit, search, new, list, calendar, developer, planner, release, workflow, init |
 | **4 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and `pm-delivery-chain` (orchestrated delivery) |
@@ -29,7 +29,7 @@ claude plugin marketplace add /path/to/pm-cli
 # claude plugin marketplace add unbraind/pm-cli
 ```
 
-This installs all 18 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid TUI tracking, and the session hook in one step.
+This installs all 21 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid TUI tracking, and the session hook in one step.
 
 ### Option B: Legacy marketplace alias (also works)
 
@@ -45,7 +45,7 @@ Both `pm` and `pm-cli` marketplace IDs resolve to the same plugin.
 claude mcp add --transport stdio pm-mcp -- npx -y @unbrained/pm-cli pm-mcp
 ```
 
-This gives you the 18 MCP tools but not the skills, slash commands, or session hook.
+This gives you the 21 MCP tools but not the skills, slash commands, or session hook.
 
 ### Option D: Direct `.mcp.json` (project-scoped MCP only)
 
@@ -159,6 +159,9 @@ Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
 | `pm_comments` | List or add comments |
 | `pm_files` | Link/unlink files |
 | `pm_docs` | Link/unlink docs |
+| `pm_notes` | List or add notes |
+| `pm_learnings` | List or add learnings |
+| `pm_deps` | List/add/remove dependencies |
 | `pm_test` | Link or run tests |
 | `pm_validate` | Run validation checks |
 | `pm_health` | Run health diagnostics |
@@ -171,7 +174,7 @@ Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
 |------|---------|
 | `pm_run` | Any pm action not covered above — pass `action` field |
 
-**`pm_run` actions:** `init`, `calendar`, `activity`, `aggregate`, `dedupe-audit`, `normalize`, `reindex`, `extension`, `history`, `stats`, `append`, `notes`, `learnings`, `test-all`, `comments-audit`, `gc`, `templates-list`, `templates-save`, `templates-show`, `test-runs-list`, `test-runs-status`, `test-runs-logs`, `test-runs-stop`, `test-runs-resume`, `config`, `completion`
+**`pm_run` actions:** `init`, `calendar`, `activity`, `aggregate`, `dedupe-audit`, `normalize`, `reindex`, `extension`, `history`, `stats`, `append`, `test-all`, `comments-audit`, `gc`, `templates-list`, `templates-save`, `templates-show`, `test-runs-list`, `test-runs-status`, `test-runs-logs`, `test-runs-stop`, `test-runs-resume`, `config`, `completion`
 
 ## Hybrid TUI Sync Pattern
 

package/plugins/pm-claude/agents/pm-coordinator.md

@@ -29,7 +29,7 @@ For batch audits spanning many items, create one top-level `TaskCreate` for the
 
 ## Tools Available
 
-Use the `pm-mcp` MCP server tools: `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_plan`, and `pm_run` for all other operations.
+Use the `pm-mcp` MCP server tools: `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_notes`, `pm_learnings`, `pm_deps`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_plan`, and `pm_run` for all other operations.
 
 Also use Claude Code's built-in `TaskCreate` and `TaskUpdate` tools for TUI panel display.