@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/.agents/skills/pm-user/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: pm-user
+description: Guides user- and operator-facing pm-cli workflows for intake, triage, prioritization, planning, and reporting under a bounded token budget. Use when routing requests into pm items, organizing a backlog, or reporting on state without implementing code changes.
+license: MIT
+compatibility: Works in terminal-based agent harnesses that execute pm CLI commands.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: operator-workflow
+---
+
+# pm User Skill
+
+Planning and coordination work where the output is clean tracker state, not
+code. The tracker is the project's context: an item is well-formed when another
+agent can rebuild the full situation from it alone.
+
+## Load Order
+
+| Tier | Load                                  | Cost      | When                           |
+| ---- | ------------------------------------- | --------- | ------------------------------ |
+| 0    | This file                             | ~650 tok  | Always.                        |
+| 1    | `pm context --limit 10`               | ~2.1k     | Orient in an existing project. |
+| 1    | `pm search "<terms>" --limit 10`      | ~0.5-1k   | Before creating anything.      |
+| 2    | `pm guide <topic> --depth brief`      | ~0.6-1k   | An unfamiliar family.          |
+| 3    | `references/*.md` below               | ~0.3-1k   | Procedure detail.              |
+
+Optional deep routing that never goes stale:
+
+```bash
+pm install guide-shell --project
+pm guide quickstart
+pm guide commands --depth brief
+```
+
+## Non-Negotiables
+
+- Author identity is detected automatically. **Never pass `--author`, never set
+  `PM_AUTHOR`.**
+- Search before creating; record the duplicate check as a create-time comment.
+- Never delete items by search match — only by exact id.
+- Prefer appending (`pm comments`, `pm notes`) over rewriting item content.
+- Never assert an item's state from memory. Read it live first.
+
+## Intake Loop
+
+```bash
+pm context --limit 10
+pm search "<request keywords>" --limit 10
+pm list-open --limit 20 --output-include id,title,type,priority
+# reuse if it exists; otherwise create with lineage
+pm create --create-mode progressive \
+  --title "..." --description "..." --type Task --status open \
+  --parent <epic-or-feature-id> \
+  --dep "id=<origin-item>,kind=discovered_from" \
+  --ac "..." --priority 1 --risk medium --confidence medium
+pm comments <ID> "Duplicate check: searched <terms>; nearest existing is <id> which covers <scope>."
+```
+
+## What Makes An Item Well-Formed
+
+Use the metadata the tracker actually has. An item carrying only a title is a
+placeholder, not a tracked unit of work.
+
+| Field                                    | Why it matters                                     |
+| ---------------------------------------- | -------------------------------------------------- |
+| `--type`                                 | Routes into the right lifecycle and changelog bucket|
+| `--parent`                               | Places the item in the ladder                       |
+| `--dep "id=..,kind=.."`                  | Makes lineage machine-readable                      |
+| `--ac`                                   | Defines done without argument                       |
+| `--expected-result` / `--actual-result`  | Turns a defect into a reproducible claim            |
+| `--priority`, `--risk`, `--confidence`   | Lets selection rank without a human                 |
+| `--estimate`, `--deadline`               | Feeds scheduling and forecasting                    |
+| `--resolution`, `--close-reason`         | Makes the closed record answerable later            |
+
+`--risk` is an enum: `low`, `medium`, `high`, `critical`. `--ac` **replaces**
+the criteria; `--dep` **appends**.
+
+## Capability Map
+
+| Need                        | Entry                                    | Guide topic  |
+| --------------------------- | ---------------------------------------- | ------------ |
+| What should I do next       | `pm next`                                | `quickstart` |
+| Where does this project stand | `pm context`, `pm stats`               | `quickstart` |
+| Find existing work          | `pm search`, `pm list`, `pm duplicates`  | `commands`   |
+| Group and count             | `pm aggregate --group-by <field>`        | `commands`   |
+| Lineage and ordering        | `pm deps`, `pm graph <verb>`             | `graph`      |
+| Recent movement             | `pm activity`, `pm events`, `pm history` | `assurance`  |
+| Data quality                | `pm validate`, `pm health`               | `assurance`  |
+| Plan a multi-step change    | `pm plan`                                | `workflows`  |
+| Custom types and statuses   | `pm schema`, `pm config`                 | `commands`   |
+| Keep reads cheap            | `--output-*`, `--token-accounting`       | `tokens`     |
+
+## Reporting Without Loading Rows
+
+```bash
+pm stats
+pm aggregate --group-by status --json | jq '.groups'
+pm list --status open --output-include id,title,priority --output-limit 20
+```
+
+`--group-by tags` groups by the whole tag **tuple**, not by individual tag.
+Aggregate on a scalar field when a per-value count is what you want.
+
+## References
+
+| Need                              | Load                                          | Cost     |
+| --------------------------------- | --------------------------------------------- | -------- |
+| Triage and planning procedures     | [Workflows](references/WORKFLOWS.md)          | ~350 tok |
+| Prompt templates                   | [Prompts](references/PROMPTS.md)              | ~250 tok |
+| Backlog structure and item quality | [Backlog shaping](references/BACKLOG_SHAPING.md) | ~900 tok |

package/.agents/skills/pm-user/references/BACKLOG_SHAPING.md

@@ -0,0 +1,105 @@
+# Backlog Shaping
+
+How to keep a tracker readable by both people and graph algorithms as it grows
+from a handful of items to hundreds of thousands.
+
+## The Ladder
+
+Work resolves upward through typed edges to a declared outcome. A healthy
+workspace has no active item that reaches nothing.
+
+```
+Milestone (declared outcome)
+  ^ implements
+Epic / capability area
+  ^ parent
+Feature / Story / Decision
+  ^ parent
+Task / Issue / Chore
+```
+
+- `Story` states what an agent or an organization needs, in their words.
+- `Decision` records an architecture choice; open means proposed, closed means
+  accepted or rejected with rationale.
+- `Milestone` declares an outcome, not a date bucket.
+- `Plan` holds a multi-step change with durable steps and discoveries.
+
+Check the ladder:
+
+```bash
+pm graph audit --json | jq '{
+  isolated: .profile.isolated_active_nodes,
+  unreachable: .profile.outcome_unreachable_nodes,
+  outcomes: .profile.outcome_nodes
+}'
+```
+
+## Never Create A Duplicate
+
+```bash
+pm search "<distinctive phrase from the request>" --limit 10
+pm search "<second phrasing>" --limit 10
+pm list --type <likely-type> --status all --output-include id,title --output-limit 30
+pm duplicates --limit 20        # scored candidate pairs, where the corpus allows it
+```
+
+Record what you searched in a create-time comment. A duplicate check that is
+not written down cannot be audited later, and the next agent repeats it.
+
+When the request extends existing scope, extend the existing item — add
+acceptance criteria, add a child, add a typed edge. Filing a near-identical
+sibling is the most expensive mistake in a large tracker.
+
+## Prioritization That Selection Can Use
+
+`pm next` ranks from recorded metadata. Metadata you never set cannot rank.
+
+```bash
+pm update <ID> --priority 1 --risk high --confidence medium --estimate 120
+pm update <ID> --deadline 2026-09-30
+pm comments <ID> "Decision log: raised to P1 because <evidence>."
+```
+
+Ordering belongs in edges, not in priority numbers:
+
+```bash
+pm update <ID> --dep "id=<prerequisite>,kind=blocked_by"
+```
+
+Do not record the inverse `blocks` edge as well — the pair is one relationship
+and recording both creates a cycle.
+
+## Closing Well
+
+A closed item is the project's memory. Closed badly, it is a dead end.
+
+```bash
+pm close <ID> "<what shipped and what proved it>" \
+  --resolution "<how it was resolved>" \
+  --validate-close warn
+pm release <ID>
+```
+
+Fill `resolution`, `expected_result`, and `actual_result` for defects.
+`pm validate --check-resolution` reports which terminal items are missing them.
+
+Record evolution explicitly rather than letting it be inferred:
+
+```bash
+pm update <NEW> --dep "id=<OLD>,kind=supersedes"
+pm update <FIX> --dep "id=<INCIDENT>,kind=incident_from"
+pm update <TEST> --dep "id=<FEATURE>,kind=verifies"
+```
+
+## Periodic Hygiene
+
+```bash
+pm validate --check-resolution --check-history-drift
+pm health --summary
+pm graph audit
+pm list --status in_progress          # stale claims
+pm aggregate --group-by type --json
+```
+
+Fix what a diagnostic prescribes rather than only recording that it warned.
+A warning that has been carried for months is a decision that was never made.

package/.agents/skills/pm-user/references/PROMPTS.md

@@ -0,0 +1,17 @@
+# Operator Prompt Templates
+
+## Triage
+
+`Find the canonical pm item for this request. Show duplicate-check commands, then either reuse and update the item or create parent lineage + child item with explicit rationale.`
+
+## Schedule
+
+`Apply deterministic scheduling metadata (status, priority, estimate, deadline) to <ID> and leave a comment explaining the prioritization decision.`
+
+## Handoff
+
+`Prepare <ID> for handoff: append current state, blockers, and next actions; release the claim when handoff is complete.`
+
+## Closure Readiness
+
+`Validate whether <ID> is close-ready by checking acceptance criteria, linked files/tests/docs, and latest verification evidence.`

package/.agents/skills/pm-user/references/WORKFLOWS.md

@@ -0,0 +1,35 @@
+# User and Operator Workflows
+
+## Intake Workflow
+
+1. Query current context:
+
+```bash
+pm context --limit 10
+pm search "<keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+2. If existing item matches, reuse and update it.
+3. If no match exists, create parent lineage then child item.
+4. Add duplicate-check evidence in comments at creation time.
+
+## Claim and Ownership Workflow
+
+```bash
+pm claim <ID>
+pm update <ID> --status in_progress --message "Start work"
+pm comments <ID> "Owner update: <state>"
+pm release <ID>
+```
+
+## Audit-Friendly Collaboration
+
+For non-owner append-only collaboration:
+
+```bash
+pm comments <ID> --add "audit comment" --allow-audit-comment
+pm notes <ID> --add "audit note" --allow-audit-comment
+pm update <ID> --dep "id=<id>,kind=related,author=<author>,created_at=now" --allow-audit-dep-update
+```

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.26"
+    "version": "2026.8.28"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.26",
+      "version": "2026.8.28",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 2026.8.28 - 2026-08-28
+
+### Fixed
+
+- Repository test runner inherits production Sentry and turns negative CLI fixtures into release-blocking incidents ([pm-5ug5xq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5ug5xq.toon))
+- Broad squash commits overflow hosted-analysis tree lookup and falsely lose reviewed PR provenance ([pm-gactwj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gactwj.toon))
+- Golden agent-transcript replay: measure tokens-per-completed-task as a CI-visible DX regression gate ([pm-8pnj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-8pnj.toon))
+- Unknown-option refusal textual flags bypass structured global-option filtering ([pm-x4wbui](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x4wbui.toon))
+- Agent-task transcript recovery accepts a refusal as a successful retry ([pm-o360q6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o360q6.toon))
+- Close lifecycle bypasses reproducible process clock ([pm-hmpu4p](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-hmpu4p.toon))
+- GH-1132: opt-in idempotent annotation append (ifAbsent/--if-absent) prevents retry-driven context duplication; duplicate appends remain available by default ([pm-ea1yh2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ea1yh2.toon))
+- Agent-task transcripts accept declared no-effect and partial-effect successful exits ([pm-wanwyc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wanwyc.toon))
+- Agent-task baselines accept missing task and composite token ceilings ([pm-aksavu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-aksavu.toon))
+- Agent-task closeout claims lack linked full-verification commands ([pm-ervmsc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ervmsc.toon))
+- CLI transport-floor RSS admission false-fails on single-sample page noise ([pm-pz49xc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pz49xc.toon))
+- Unknown-option refusals identify the actual rejected flag and fail closed at delimiters ([pm-fo8g7j](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fo8g7j.toon))
+- Agent-task gate accepts incidental substrings as required-field completeness ([pm-o7u08u](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o7u08u.toon))
+- Completed-task transcripts require terminal success, exclusive refusal metadata, and complete recovery ([pm-wa39rl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wa39rl.toon))
+- Agent-task token replay trusts missing or incorrect accounting estimates ([pm-ok2kdn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ok2kdn.toon))
+
+### Security
+
+- GH-1131: macOS Node 24 nightly cannot create the Skills-over-MCP special-file socket fixture ([pm-k23c4c](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-k23c4c.toon))
+
+## 2026.8.27 - 2026-08-27
+
+### Added
+
+- Tiered contract-driven help: one-screen core help, full surface via pm help --all, generated from the contract table ([pm-e2bq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-e2bq.toon))
+- Skills over MCP: discoverable version-coherent pm workflows with progressive disclosure, capability requirements, and token budgets ([pm-8nzivt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-8nzivt.toon))
+- MCP Apps for pm: interactive graph, context, plan, assurance, and long-operation views with consent-safe action boundaries ([pm-pznhee](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-pznhee.toon))
+
+### Fixed
+
+- GH-859: pm-beads source export can omit Beads comment bodies and events ([pm-tpwde6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tpwde6.toon))
+- pm get silently discards --output-include field names because entity reads bind the flag to sections while collection reads bind it to fields, and the omission receipt reports no omissions either way ([pm-0k19l7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0k19l7.toon))
+- GH-860: pm-beads --preserve-source-ids changes source ID casing ([pm-f7jj9b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-f7jj9b.toon))
+- GH-862: pm-beads must map Beads close reasons into native resolution metadata ([pm-gus5ft](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gus5ft.toon))
+- GH-1118: natural-language word-number titles trigger duplicate issue-code false positives ([pm-blvfye](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-blvfye.toon))
+- Published-artifact verification rejects the new pm-mcp-http bin before executing its healthy published entrypoint ([pm-fpdne3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fpdne3.toon))
+
+### Other
+
+- Consolidate package lifecycle: extension/package/install/upgrade under a single pm package namespace ([pm-tnud](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-tnud.toon))
+- Refresh compatible ESLint 10.9.1 and Node type 26.3 patches ([pm-crkmmr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-crkmmr.toon))
+- MCP 2026-07-28 conformance and release gate: official schema matrix, protocol-era adapters, real transports, adversarial cases, and published consumers ([pm-55yf1t](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-55yf1t.toon))
+
 ## 2026.8.26 - 2026-08-26
 
 ### Added
@@ -442,7 +489,6 @@
 - Sentry PM-CLI-2Q: expected snapshot-name validation is captured as a high production error ([pm-qyg51h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qyg51h.toon))
 - The release gate classifies production errors by message prose and reads none of the 236 error codes the product declares, so every waiver is a latent re-block and a broad substring is a silent waiver ([pm-dqtzva](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dqtzva.toon))
 - The mandatory command-wiring replication set is enforced only by a prose checklist, and the census shows partial application is the single largest recurring defect class in the record ([pm-7rrqsk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7rrqsk.toon))
-- pm get silently discards --output-include field names because entity reads bind the flag to sections while collection reads bind it to fields, and the omission receipt reports no omissions either way ([pm-0k19l7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0k19l7.toon))
 - GH-919: \_workspace author-attribution coordinates cannot be acknowledged ([pm-ety1qc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ety1qc.toon))
 - pm comments write response replays the entire accumulated history, so one append can emit hundreds of comments ([pm-9stazf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9stazf.toon))
 - GH-457: pm health hangs during vectorization check with no output (never-block violation) ([pm-tu71](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tu71.toon))
@@ -865,10 +911,10 @@
 
 ### Other
 
+- CLI transport overhead budget: gate the per-invocation bootstrap floor and the CLI-vs-SDK delta, not just absolute scale numbers ([pm-yse5dt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yse5dt.toon))
 - CI/CD + test-suite performance: in-process CLI runner and dedupe redundant matrix legs ([pm-7rlp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-7rlp.toon))
 - ADR: agent identity model — stable author namespace plus structured harness, model, and session provenance ([pm-qwuber](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-qwuber.toon))
 - Public SDK surface shape: 881 exports behind one flat entrypoint with no capability tiering and a 250ms eager import cost ([pm-38bskj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-38bskj.toon))
-- CLI transport overhead budget: gate the per-invocation bootstrap floor and the CLI-vs-SDK delta, not just absolute scale numbers ([pm-yse5dt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yse5dt.toon))
 
 ## 2026.7.25 - 2026-07-25
 
@@ -991,12 +1037,12 @@
 
 ### Fixed
 
+- GH-576: unknown-command help probes return structured non-zero errors ([pm-bu1m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bu1m.toon))
 - Sentry PM-CLI-2G: make merge-driver installation permission failures actionable ([pm-bnmlsc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bnmlsc.toon))
 - Sentry PM-CLI-2F: classify manifest-proven torn bundle call-time TypeError ([pm-pz7xtx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pz7xtx.toon))
 - Compatibility gate rejects compact legacy create envelopes after release promotion ([pm-pkdpyz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pkdpyz.toon))
 - Sentry PM-CLI-2E: directory-shaped settings.json crashes CLI bootstrap ([pm-k0nl2w](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-k0nl2w.toon))
 - Sentry PM-CLI-2D: storage-integrity history scan reads .jsonl directories as files ([pm-o1c53b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o1c53b.toon))
-- GH-576: unknown-command help probes return structured non-zero errors ([pm-bu1m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bu1m.toon))
 - GH-551: dependency seeds accept global source_kind and preserve cross-workspace IDs ([pm-topu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-topu.toon))
 - GH-595: list JSON always emits total/has_more/truncated/next_cursor and omits unset filters ([pm-wrss](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wrss.toon))
 - GH-623: opt-in post-merge history reconciliation hook and one-command verify repair ([pm-mfkv92](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mfkv92.toon))
@@ -1462,6 +1508,7 @@
 
 ### Added
 
+- pm package/extension init --capability profile: scaffold a project-profile starter package ([pm-h2hk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h2hk.toon))
 - Describe --markdown writes reference docs to a file ([pm-u2tm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-u2tm.toon))
 - Complete scaffold capability matrix: --capability renderers/parser/preflight/services starters ([pm-i5p5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-i5p5.toon))
 - Scaffolded & authored command-bearing extensions reliably activate for their own commands ([pm-yxb5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-yxb5.toon))
@@ -1469,7 +1516,6 @@
 - pm next: recommend the next actionable (unblocked, ready) work item with rationale + blocked companion ([pm-nj90](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-nj90.toon))
 - Add pm package / pm packages shell completion (bash/zsh/fish), including the package-only --declarative flag ([pm-mthy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mthy.toon))
 - Project profile author-time validation: lintProjectProfile + assertProjectProfile + pm profile lint ([pm-j1fj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-j1fj.toon))
-- pm package/extension init --capability profile: scaffold a project-profile starter package ([pm-h2hk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h2hk.toon))
 - SDK + CLI: render extension/package surfaces to Markdown reference docs (renderExtensionSurfaceMarkdown + describe --markdown) ([pm-dmum](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-dmum.toon))
 - pm package/extension init --capability schema: scaffold custom item type/field/migration starter ([pm-d1ig](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-d1ig.toon))
 - First-party baseline profile package built on public SDK primitives ([pm-a7o4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-a7o4.toon))

package/README.md

@@ -60,14 +60,17 @@ npx --yes @unbrained/pm-cli@latest --help
 `pm` packages use the same package-first vocabulary:
 
 ```bash
-pm install '*'
-pm install ./my-package
+pm package install '*'
+pm package install ./my-package
 pm package manage --project
 pm package doctor --detail summary
-pm upgrade --dry-run
+pm package upgrade --dry-run
 ```
 
-The legacy `pm extension ...` command remains available for existing automation.
+The hidden legacy `pm extension ...`, `pm install ...`, and `pm upgrade ...`
+aliases remain available for existing automation. They preserve canonical output
+and emit one migration hint on stderr unless `ux.deprecation_hints` is disabled;
+for example, `pm install guide-shell --project` maps to the canonical command.
 
 ## 60 Second Example
 
@@ -108,7 +111,7 @@ pm list --status in_progress --limit 20
 
 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).
 
-For token-aware local routing, install `guide-shell` with `pm install guide-shell --project`, then use `pm guide workflows` and drill into related topics (`commands`, `skills`, `release`) only when needed.
+For token-aware local routing, install `guide-shell` with `pm package install guide-shell --project`, then use `pm guide workflows` and drill into related topics (`commands`, `skills`, `release`) only when needed.
 
 ## Core Model
 

package/dist/cli/commander-usage.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="48877bbb-17bf-5a78-91fa-19a2f2f4c2be")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8879d491-9158-548c-bfbd-8ab57d8eb936")}catch(e){}}();
 import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, locateItem, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { PM_CORE_COMMAND_NAMES, resolveSubcommandFlagContractsForCommand, } from "../sdk/cli-contracts.js";
@@ -525,16 +525,20 @@ export function isKnownHelpCommandPath(root, commandPathTokens) {
         return true;
     }
     let current = root;
-    let matchedAny = false;
-    for (const token of commandPathTokens) {
+    for (const [tokenIndex, token] of commandPathTokens.entries()) {
         const next = resolveChildCommandByToken(current, token);
         if (!next) {
-            return matchedAny;
+            if (current.commands.some((candidate) => candidate.name() !== "help")) {
+                return false;
+            }
+            const declaredArguments = current.registeredArguments;
+            return (declaredArguments.length > 0 &&
+                (declaredArguments.at(-1)?.variadic === true ||
+                    commandPathTokens.length - tokenIndex <= declaredArguments.length));
         }
-        matchedAny = true;
         current = next;
     }
-    return matchedAny;
+    return true;
 }
 async function resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName) {
     try {
@@ -763,4 +767,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=48877bbb-17bf-5a78-91fa-19a2f2f4c2be
+//# debugId=8879d491-9158-548c-bfbd-8ab57d8eb936

package/dist/cli/error-guidance.js

@@ -1,9 +1,10 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4bdb7fcf-dd74-57bc-8a0e-07539095462e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ca79853d-468c-5522-b5f9-6509c66e3d9b")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { projectPmDiagnosticOutput, projectPmDiagnosticText, } from "../sdk/cli-contracts/agent-output-contracts.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
+import { stripGlobalBootstrapTokens } from "../sdk/cli-bootstrap.js";
 /** Compact an error envelope to fields that change the caller's next action. */
 export function projectLeanErrorEnvelope(envelope) {
     const { why: _why, title: _title, ...actionable } = envelope;
@@ -207,6 +208,7 @@ function renderRecoveryBundle(recovery) {
         return [];
     }
     const lines = ["Recovery bundle:"];
+    appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
     appendRecoveryTextLine(lines, "attempted_command", normalized.attempted_command);
     appendRecoveryListLine(lines, "normalized_args", normalized.normalized_args, " ");
     if (normalized.parsed_positionals &&
@@ -231,7 +233,6 @@ function renderRecoveryBundle(recovery) {
     if (normalized.option_scope !== undefined) {
         lines.push(`  option_scope: ${normalized.option_scope}`);
     }
-    appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
     if (typeof normalized.retry_after_ms === "number") {
         lines.push(`  retry_after_ms: ${normalized.retry_after_ms}`);
     }
@@ -307,15 +308,36 @@ function attachStructuredGuidanceDetails(payload, message) {
 function resolveRefusalCandidateFlag(message, normalizedArgs) {
     if (message.flag)
         return message.flag;
-    return message.recovery?.provided_fields?.find((field) => field !== "--json" &&
-        field !== "--quiet" &&
-        normalizedArgs.includes(field));
+    const isAdmissibleCandidate = (flag) => {
+        const canonicalFlag = flag.split("=", 1)[0];
+        return (stripGlobalBootstrapTokens([canonicalFlag]).length > 0 &&
+            !["--help", "--no-changed-fields", "--version"].includes(canonicalFlag) &&
+            normalizedArgs.some((argument) => argument === canonicalFlag ||
+                argument.startsWith(`${canonicalFlag}=`)));
+    };
+    const mentionedFlag = [
+        ...`${message.title} ${message.happened}`.matchAll(/--[A-Za-z0-9][A-Za-z0-9_-]*/gu),
+    ]
+        .map((match) => match[0])
+        .find((flag) => isAdmissibleCandidate(flag));
+    if (mentionedFlag)
+        return mentionedFlag;
+    return message.recovery?.provided_fields
+        ?.map((field) => field.split("=", 1)[0])
+        .find((field) => isAdmissibleCandidate(field));
 }
 function resolveRefusalRejectedValue(message, normalizedArgs, candidateFlag) {
     if (message.value !== undefined)
         return message.value;
     if (candidateFlag) {
-        return normalizedArgs[normalizedArgs.indexOf(candidateFlag) + 1];
+        const candidateArgument = normalizedArgs.find((argument) => argument === candidateFlag || argument.startsWith(`${candidateFlag}=`));
+        if (candidateArgument?.startsWith(`${candidateFlag}=`)) {
+            return candidateArgument.slice(candidateFlag.length + 1);
+        }
+        const candidateIndex = normalizedArgs.indexOf(candidateFlag);
+        return candidateIndex >= 0
+            ? normalizedArgs[candidateIndex + 1]
+            : undefined;
     }
     const allowedValues = message.recovery?.allowed_values;
     if (!allowedValues?.length)
@@ -941,6 +963,34 @@ function buildUnknownOptionNextSteps(optionName, commandName, suggestions, candi
             : undefined,
     ].filter((entry) => typeof entry === "string");
 }
+/**
+ * Publish a shell-free correction only when removing the unknown token leaves
+ * positional ownership unambiguous; explicit producer guidance stays authoritative.
+ */
+function resolveUnknownOptionRetry(context, optionName) {
+    if (context.suggestedRetryCommand !== undefined) {
+        return { retryCommand: context.suggestedRetryCommand };
+    }
+    const normalizedArgs = context.normalizedInvocationArgs;
+    if (normalizedArgs === undefined)
+        return {};
+    if (normalizedArgs.filter((argument) => argument === optionName || argument.startsWith(`${optionName}=`)).length !== 1) {
+        return {};
+    }
+    const optionIndex = normalizedArgs.findIndex((argument) => argument === optionName || argument.startsWith(`${optionName}=`));
+    if (optionIndex < 0 ||
+        normalizedArgs.includes("--") ||
+        (!normalizedArgs[optionIndex]?.includes("=") &&
+            optionIndex !== normalizedArgs.length - 1 &&
+            normalizedArgs[optionIndex + 1]?.startsWith("-") !== true)) {
+        return {};
+    }
+    const suggestedRetryArgs = stripGlobalBootstrapTokens(normalizedArgs.filter((_, index) => index !== optionIndex));
+    return {
+        retryCommand: renderPmCommand(suggestedRetryArgs),
+        suggestedRetryArgs,
+    };
+}
 function buildUnknownOptionGuidance(message, commandName, context) {
     const unknownOption = message.match(/unknown option '([^']+)'/);
     if (!unknownOption) {
@@ -949,7 +999,7 @@ function buildUnknownOptionGuidance(message, commandName, context) {
     const guidanceContext = context ?? {};
     const optionName = unknownOption[1];
     const suggestions = normalizeOptionFlags(guidanceContext.unknownOptionSuggestions) ?? [];
-    const retryCommand = guidanceContext.suggestedRetryCommand;
+    const { retryCommand, suggestedRetryArgs } = resolveUnknownOptionRetry(guidanceContext, optionName);
     if (commandName === "update" &&
         (optionName === "--file" || optionName === "--doc")) {
         return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
@@ -966,10 +1016,14 @@ function buildUnknownOptionGuidance(message, commandName, context) {
         happened: `Commander does not recognize option ${optionName} for this command path.`,
         required: UNKNOWN_OPTION_REQUIRED_BY_SCOPE[candidateContext.optionScope],
         why: "Option contracts are command-specific and intentionally validated.",
+        flag: optionName,
+        value: optionName,
         examples,
         nextSteps,
         recovery: buildCommanderRecoveryPayload(context, {
             suggested_flags: suggestions.length > 0 ? suggestions : undefined,
+            suggested_retry: retryCommand,
+            suggested_retry_args: suggestedRetryArgs,
             candidate_commands: candidateContext.otherCommands,
             candidate_commands_total: candidateContext.candidateTotal || undefined,
             candidate_commands_truncated: guidanceContext.unknownOptionOtherCommandsTruncated,
@@ -1297,4 +1351,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=4bdb7fcf-dd74-57bc-8a0e-07539095462e
+//# debugId=ca79853d-468c-5522-b5f9-6509c66e3d9b

package/dist/cli/help-content.d.ts

@@ -39,6 +39,8 @@ declare function renderDetailedHelpBundle(bundle: HelpBundle): string;
 export declare function normalizeHelpCommandPath(commandPath: string): string;
 /** Implements resolve help detail mode for the public runtime surface of this module. */
 export declare function resolveHelpDetailMode(argv: string[]): HelpDetailMode;
+/** Whether an invocation requests the complete public command discovery tier. */
+export declare function isFullHelpDiscovery(argv: readonly string[]): boolean;
 /** Public contract for root help bundle, shared by SDK and presentation-layer consumers. */
 export declare const ROOT_HELP_BUNDLE: HelpBundle;
 /** Implements resolve help bundle for path for the public runtime surface of this module. */