pm-context

pm-context generates deterministic context packs from a pm workspace so handoffs, reviews, and agent sessions start from the same project state.

It complements the core pm context command by writing durable markdown or JSON packs for selected items and their dependency neighborhood.

Install

pm install github.com/unbraind/pm-context --project

Usage

pm context-pack --id pm-1234 --include-body --output context.md
pm context-pack --id pm-1234 --format agent
pm context-pack --id pm-1234 --format compact --recent 8
pm context-pack --ids pm-1234,pm-5678 --state blocked --format compact
pm context-pack --status in_progress --tag release --format json
pm context-pack --type Feature --include-closed --limit 20
pm context-pack --id pm-1234 --neighborhood-depth 2
pm context-pack --id pm-1234 --compress --format json
pm context-pack --id pm-1234 --include-deps --section focus --section blockers
pm context-pack --id pm-1234 --max-items 10

The command reads workspace data in-process through the typed pm SDK, so packs use the installed CLI's canonical query and relevance engines rather than a second parser. Normal pack and handoff runs record one best-effort context-usage serving event for the emitted items when an author is available; --explain does not write to the usage ledger.

Output

Markdown packs include:

• a summary with selected item counts by status and type
• focus items sorted by priority and update time
• dependency and dependent context for selected items
• linked docs and files when item metadata exposes them
• optional item bodies

JSON packs expose the same data in a stable shape for automation.

Agent handoff packs (--format agent or --format compact) are intentionally compact. They focus on the current work, visible blockers, next actions, recent activity, linked files/docs, and the exact refresh command another agent should run before continuing.

Compress mode

--compress minimizes output tokens for token-sensitive agent contexts:

• JSON output is minified (no indentation)
• Markdown and agent output have all blank lines removed

Section filtering

--section <section> selects only specific sections of the rendered output. Repeat the flag for multiple sections. Available sections:

• Markdown: summary, focus, neighborhood, neighbors, links, deps
• Agent: focus, blockers, next-actions (alias: actions), recent (alias: activity), links, deps, refresh

Dependency info

--include-deps adds per-item dependency information (dependsOn and dependedBy arrays) to the context pack and handoff output. A ## Dependencies section is rendered in markdown/agent output when present.

Max items

--max-items <n> caps the total number of items (focus + neighbors) in the pack. The SDK packer first selects candidates under a token budget with projection degradation, preserving required focus items and relevance-ranked neighbors; --max-items is then enforced as an additional hard item-count ceiling.

Command

pm context-pack

Options:

• --id <id> repeatable item ids to focus
• --ids <id,id> comma-separated focus item ids (alias for repeated --id)
• --status <status> filter by status
• --state <status> alias for --status
• --type <type> filter by type
• --kind <type> alias for --type
• --tag <tag> filter by tag
• --limit <n> maximum focus item count
• --format <markdown|json|agent|compact> output format (compact aliases agent)
• --recent <n> recent activity lines for agent/compact output (default 5)
• --output <file> write the pack to a file
• --include-body include item bodies
• --include-closed include closed/canceled items in filtered packs
• --without-neighborhood omit dependency/dependent neighbors
• --neighborhood-depth <n> include transitive neighbors up to n hops (default 1). A breadth-first walk over the dependency relationship graph in both directions (depends_on/blocked_by edges and their reverse). 0 is equivalent to --without-neighborhood; the value is capped at 5. Depth 1 is the historical default and produces byte-identical packs to prior versions. Neighbors discovered at deeper hops are still classified as neighbors (never focus), de-duplicated, and a focus item is never listed as its own neighbor.
• --compress minimize output tokens (compact JSON, no blank lines)
• --include-deps include per-item dependency info in the context pack
• --max-items <n> maximum total items (focus + neighbors) in the pack
• --explain explain the exact focus and neighborhood items that the normal selection and packing path would emit, without recording a serving event; reported ranks and scores are relative to that emitted pack, not the workspace
• --section <section> include only specific sections (repeatable): summary, focus, neighborhood, neighbors, links, deps, blockers, next-actions (alias: actions), recent (alias: activity), refresh

pm context-usage

Reports which items pm context and pm next served, and which of those were actually touched afterwards — the feedback half of "project management = context management".

pm maintains an append-only ledger at <pm_root>/runtime/context-usage.jsonl (a serve row per ranking, a touch row per mutation) and folds it into the usage_affinity signal of its built-in relevance model. Nothing surfaces the ledger itself, so an agent cannot ask what was I shown, and did I use it? This command answers that:

• conversion — share of served items followed by a same-author touch
• waste — served but never touched afterwards: context you paid tokens for and did not use
• misses — touched but never served: work the ranking failed to surface

An item counts as served only when pm marked it included — it actually made the pack. The per-item ranked column counts every appearance, so ranked - serves is how often the item lost to the token budget rather than to the ranking: tune the budget, not the query. An item that was only ever ranked and cut is never reported as waste, because the agent never saw it.

pm context-usage                          # markdown brief
pm context-usage --json                   # raw report
pm context-usage --surface next --since 7d
pm context-usage --author agent-a --limit 50

Options:

• --author <author> restrict to one recording author
• --surface <context|next> restrict serve events to one surface
• --since <when> drop events at or before an ISO timestamp or a day offset (7d, -7d, 7)
• --limit <n> maximum per-item rows (default 20)
• --format <markdown|json> output format (default markdown); pm's global --json also selects JSON

The command is strictly read-only. The ledger is pm's file, with pm's schema and pm's pruning, and it deliberately reports only what the ledger states directly — it does not compute a competing affinity score, because pm owns the decay model and a second implementation could silently disagree with the ranking it purports to explain.

Philosophy

Project management is context management. pm-context makes that concrete by turning pm's source-of-truth items into portable context that can be reviewed, sent to another agent, or attached to a pull request — and, with pm context-usage, by measuring whether that context was worth sending.

Multi-agent merge safety

This repo tracks its project management in .agents/pm/ and ships a committed .gitattributes that maps those tracker artifacts to pm-cli's field-aware Git merge drivers, so concurrent-branch tracker edits merge cleanly instead of hard-conflicting. The driver definitions live in per-clone Git config; npm install / npm ci wires them automatically via the prepare script (a portable Node guard, scripts/prepare-merge-driver.mjs: it runs pm merge install only when the pm CLI is on PATH, and no-ops cleanly otherwise so production / --omit=dev installs are not broken; being Node-based it behaves identically on POSIX shells and Windows cmd.exe). To (re)run manually: npm run merge:install.

After merging a branch that touched .agents/pm/, reconcile any residual history-hash drift with pm merge reconcile (pm-cli ≥ 2026.7.22): preview with pm merge reconcile --dry-run, apply with pm merge reconcile --message "post-merge reconcile", then confirm with pm validate, which scans the whole tracker and flags remaining history drift across every affected item (pm merge reconcile itself lists each affected stream in its output; pm history --verify <id> spot-checks one item). The field-aware driver already unions every author's content, so reconcile only re-greens the hash chain (no data loss) — see the authoritative pm-cli merge-safety guide. The older blunt pm history-repair --all remains available as a lower-level primitive.