npm - @unbrained/pm-cli - Versions diffs - 2026.6.10 → 2026.6.12 - Mend

@unbrained/pm-cli 2026.6.10 → 2026.6.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (456) hide show

package/dist/cli/help-content.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"help-content.js","sources":["cli/help-content.ts"],"sourceRoot":"/","sourcesContent":["import { Command } from \"commander\";\n\nexport interface HelpBundle {\n why: string;\n examples: string[];\n tips?: string[];\n}\n\nexport interface HelpNarrative {\n intent: string;\n examples: string[];\n tips: string[];\n detail_mode: HelpDetailMode;\n}\n\nexport type HelpDetailMode = \"compact\" \| \"detailed\";\n\nfunction renderCompactHelpBundle(bundle: HelpBundle): string {\n const lines: string[] = [\n \"\",\n \"Intent:\",\n ` ${bundle.why}`,\n ];\n if (bundle.examples.length > 0) {\n lines.push(\"\", \"Example:\");\n lines.push(` ${bundle.examples[0]}`);\n }\n lines.push(\"\", \"Need deeper rationale and more examples?\");\n lines.push(\" Re-run with --explain.\");\n return lines.join(\"\\n\");\n}\n\nfunction renderDetailedHelpBundle(bundle: HelpBundle): string {\n const lines: string[] = [\n \"\",\n \"Why use this command:\",\n ` ${bundle.why}`,\n \"\",\n \"Examples:\",\n ...bundle.examples.map((example) => ` ${example}`),\n ];\n if (bundle.tips && bundle.tips.length > 0) {\n lines.push(\"\", \"Tips:\");\n lines.push(...bundle.tips.map((tip) => ` - ${tip}`));\n }\n return lines.join(\"\\n\");\n}\n\nfunction renderHelpBundle(bundle: HelpBundle, detailMode: HelpDetailMode): string {\n if (detailMode === \"detailed\") {\n return renderDetailedHelpBundle(bundle);\n }\n return renderCompactHelpBundle(bundle);\n}\n\nexport function normalizeHelpCommandPath(commandPath: string): string {\n return commandPath\n .trim()\n .toLowerCase()\n .split(/\\s+/)\n .filter((part) => part.length > 0)\n .join(\" \");\n}\n\nconst HELP_PATH_ALIASES: Record<string, string> = {\n cal: \"calendar\",\n ctx: \"context\",\n};\n\nfunction findDirectChildCommand(parent: Command, name: string): Command \| null {\n return parent.commands.find((entry) => entry.name() === name) ?? null;\n}\n\nfunction findCommandByPath(root: Command, pathParts: string[]): Command \| null {\n let current: Command = root;\n for (const part of pathParts) {\n const next = findDirectChildCommand(current, part);\n if (!next) {\n return null;\n }\n current = next;\n }\n return current;\n}\n\nfunction attachBundleByPath(root: Command, commandPath: string, bundle: HelpBundle, detailMode: HelpDetailMode): void {\n const command = findCommandByPath(root, commandPath.split(\" \").filter((part) => part.length > 0));\n if (!command) {\n return;\n }\n command.addHelpText(\"after\", renderHelpBundle(bundle, detailMode));\n}\n\nexport function resolveHelpDetailMode(argv: string[]): HelpDetailMode {\n if (argv.includes(\"--explain\")) {\n return \"detailed\";\n }\n return \"compact\";\n}\n\nconst HELP_BY_COMMAND_PATH: Record<string, HelpBundle> = {\n init: {\n why: \"Bootstraps tracker storage and settings so all other commands can run safely.\",\n examples: [\n \"pm init\",\n \"pm init acme\",\n \"pm init --preset minimal\",\n \"pm init --agent-guidance add\",\n \"pm init --defaults --with-packages\",\n ],\n tips: [\n \"Run this once per repository before create/list/update commands.\",\n \"Use --preset for non-interactive automation; omit it in a TTY to use the setup wizard.\",\n \"Use --agent-guidance add to inject compact AGENTS/CLAUDE workflow guidance, or --agent-guidance status to inspect missing guidance without modifying files.\",\n \"Use --with-packages when agents need bundled commands such as calendar and templates available immediately.\",\n ],\n },\n config: {\n why: \"Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.\",\n examples: [\n 'pm config project get definition-of-done',\n 'pm config project set definition-of-done --criterion \"tests pass\"',\n \"pm config project set item-format --format toon\",\n \"pm config project set sprint-release-format-policy --policy strict_error\",\n \"pm config project set governance-preset --policy minimal\",\n \"pm config project set governance-ownership-enforcement --policy none\",\n \"pm config project set test-result-tracking --policy enabled\",\n \"pm config global set telemetry-tracking --policy disabled\",\n ],\n },\n extension: {\n why:\n \"Compatibility command for package-backed runtime extension lifecycle operations across project or global scope.\",\n examples: [\n \"pm install ./my-package --project\",\n \"pm install '' --project\",\n \"pm package doctor --project --detail summary\",\n \"pm package manage --global\",\n \"pm package activate sample-ext --project\",\n \"pm package deactivate sample-ext --project\",\n \"pm package uninstall sample-ext --global\",\n \"pm extension explore --project\",\n \"pm extension manage --global\",\n \"pm extension doctor --detail deep\",\n ],\n tips: [\n \"Prefer pm install and pm package in new user-facing automation.\",\n \"Use pm extension when maintaining existing extension-specific scripts or debugging the compatibility runtime directly.\",\n \"Bundled aliases beads and todos resolve to package-shipped extension sources.\",\n \"Use --gh/--github shorthand for GitHub sources and --ref to pin a branch, tag, or ref.\",\n \"Install updates settings activation state automatically unless extension allowlist mode is unchanged.\",\n \"Use --adopt for single-extension adoption and --adopt-all to bulk-register unmanaged installs as managed without reinstalling.\",\n \"Use --manage for concise triage summaries and remediation-oriented diagnostics alongside full extension details.\",\n \"Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads.\",\n ],\n },\n package: {\n why:\n \"Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.\",\n examples: [\n \"pm install npm:@scope/pm-package --project\",\n \"pm package install ./my-package --project\",\n \"pm package doctor --project --detail deep\",\n \"pm package manage --project --runtime-probe\",\n \"pm package activate sample-ext --project\",\n \"pm upgrade --packages-only --dry-run\",\n ],\n tips: [\n \"Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.\",\n \"Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.\",\n \"Use --dry-run before upgrade when automation needs a deterministic plan.\",\n ],\n },\n \"package init\": {\n why: \"Generates an installable starter pm package with package metadata and a root extension entrypoint.\",\n examples: [\n \"pm package init ./my-package\",\n \"pm install ./my-package --project\",\n \"pm package doctor --project --detail summary\",\n ],\n tips: [\n \"The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.\",\n \"Use package doctor after changes to verify activation, policy, and collision diagnostics.\",\n ],\n },\n \"package install\": {\n why: \"Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.\",\n examples: [\n \"pm package install ./my-package --project\",\n \"pm install npm:pm-changelog --project\",\n \"pm package install --github org/repo/packages/my-pm-package --ref main\",\n ],\n tips: [\n \"Prefer the top-level pm install alias in scripts when only installation is needed.\",\n \"Run pm package manage or pm package doctor after installing external packages.\",\n ],\n },\n \"package catalog\": {\n why: \"Lists bundled first-party package catalog metadata and compact field projections.\",\n examples: [\n \"pm package catalog --project\",\n \"pm package catalog --project --fields alias,installed,install_command\",\n \"pm package list --project --fields alias,package_name,category\",\n ],\n tips: [\n \"Use --fields for low-token package discovery in agent loops.\",\n \"External npm package discovery still belongs to npm search.\",\n ],\n },\n \"extension init\": {\n why: \"Generates an installable starter runtime extension with manifest and entrypoint files.\",\n examples: [\n \"pm extension init ./my-extension\",\n \"pm extension --install --project ./my-extension\",\n \"pm extension --doctor --project --detail summary\",\n ],\n tips: [\n \"Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold.\",\n ],\n },\n \"extension install\": {\n why: \"Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.\",\n examples: [\n \"pm extension install ./my-extension --project\",\n \"pm extension --install --project ./my-extension\",\n \"pm extension doctor --project --detail summary\",\n ],\n tips: [\"Prefer pm install or pm package install for new package-first automation.\"],\n },\n \"extension catalog\": {\n why: \"Compatibility view of bundled package catalog metadata.\",\n examples: [\n \"pm extension catalog --project\",\n \"pm extension catalog --project --fields alias,installed,install_command\",\n ],\n tips: [\"Prefer pm package catalog in new user-facing workflows.\"],\n },\n install: {\n why: \"Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.\",\n examples: [\n \"pm install '' --project\",\n \"pm install ./packages/pm-todos --project\",\n \"pm install npm:@scope/pm-package --global\",\n \"pm install --github org/repo/packages/my-pm-package --ref main\",\n ],\n tips: [\"Installed packages are recorded in managed state and can be inspected with pm package manage.\"],\n },\n upgrade: {\n why: \"Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.\",\n examples: [\n \"pm upgrade --dry-run\",\n \"pm upgrade --packages-only --project\",\n \"pm upgrade todos --dry-run\",\n \"pm upgrade --cli-only --repair\",\n \"pm upgrade --tag next --dry-run\",\n ],\n tips: [\n \"Omit target to include the CLI/SDK plus all managed packages in the selected scope.\",\n \"Pass a target to refresh one managed package by name, directory, package name, or source.\",\n \"Use --packages-only in repository automation when the global CLI should not be changed.\",\n ],\n },\n create: {\n why: \"Creates a new planning item with deterministic metadata and history.\",\n examples: [\n 'pm create --title \"Harden lock flow\" --description \"Improve stale lock handling\" --type Task --status open --priority 1 --message \"Create lock hardening task\" --create-mode progressive',\n 'pm create --title \"Weekly planning sync\" --description \"Recurring coordination meeting\" --type Meeting --schedule-preset lightweight',\n 'pm create --title \"Asset: Hero model\" --description \"Track playable model asset\" --type Asset --status open --priority 1 --message \"Create asset item\" --type-option category=Character --dep \"id=pm-epic01,kind=parent,author=codex-agent,created_at=now\" --comment \"author=codex-agent,created_at=now,text=Why this asset item exists.\" --note \"author=codex-agent,created_at=now,text=Initial implementation note.\" --learning \"author=codex-agent,created_at=now,text=Durable lesson placeholder.\" --file \"path=src/assets/hero.glb,note=tracked asset\" --test \"command=node scripts/run-tests.mjs test,timeout_seconds=240\" --doc \"path=README.md,note=asset docs\"',\n ],\n tips: [\n \"Use --schedule-preset lightweight for Reminder/Meeting/Event when you want minimal required create inputs.\",\n \"Use --type <value> to load type-aware policy guidance in --help output.\",\n ],\n },\n update: {\n why: \"Mutates existing item fields while preserving history and lock safety.\",\n examples: [\n 'pm update pm-a1b2 --status in_progress --message \"Start implementation\"',\n 'pm update pm-a1b2 --unset close-reason --message \"Clear stale close reason after reopen\"',\n 'pm update pm-a1b2 --unset assignee --deadline +2d --message \"Replan ownership and deadline\"',\n 'pm update pm-a1b2 --body \"Backfilled body text for legacy item\" --message \"Normalize missing body\"',\n ],\n tips: [\n 'Use \"pm close <ID> <TEXT>\" to close items instead of --status closed.',\n \"When reopening from closed to a non-terminal status, update clears stale close_reason unless explicitly set via --close-reason.\",\n 'Use \"pm append <ID> --body <text>\" for additive notes; use update --body to replace body content.',\n ],\n },\n \"update-many\": {\n why: \"Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.\",\n examples: [\n \"pm update-many --filter-status open --status in_progress --dry-run\",\n 'pm update-many --filter-tag wave:7 --replace-tests --test \"command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,timeout_seconds=240\"',\n 'pm update-many --filter-tag governance --reviewer maintainer-review --message \"Normalize reviewer metadata\"',\n \"pm update-many --rollback ckpt-abc123\",\n ],\n tips: [\n \"Use --dry-run first to inspect proposed changes before apply mode.\",\n \"Linked-array mutation flags mirror pm update semantics (for example --replace-tests, --clear-files, and repeatable --doc/--note seeds).\",\n \"Checkpoints are enabled by default for apply mode and can be restored with --rollback.\",\n ],\n },\n \"close-many\": {\n why: \"Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints — unlike update-many --status closed, which bypasses close validation.\",\n examples: [\n 'pm close-many --filter-sprint S-12 --reason \"Sprint S-12 acceptance criteria met\" --dry-run',\n 'pm close-many --filter-tag wave:7 --reason \"Superseded by redesign\" --validate-close warn',\n 'pm close-many --ids pm-a,pm-b,pm-c --reason \"Closed in batch\" --resolution \"Verified by integration suite\"',\n \"pm close-many --rollback close-many-20260604-abc123\",\n ],\n tips: [\n \"At least one filter (--filter-* or --ids) is required so close-many never matches every item.\",\n \"Already-terminal matches are skipped by default; pass --force to re-close them.\",\n \"Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.\",\n \"Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>.\",\n ],\n },\n normalize: {\n why:\n \"Scans items for low-signal lifecycle metadata drift, emits deterministic per-item plans, and optionally applies normalized metadata updates with update-style safety checks.\",\n examples: [\n \"pm normalize --dry-run\",\n \"pm normalize --filter-status in_progress --dry-run\",\n 'pm normalize --filter-status closed --apply --author \"codex-agent\" --message \"Normalize closure metadata\"',\n ],\n tips: [\n \"Dry-run mode is the default; pass --apply only after reviewing planned changes.\",\n \"Apply mode honors ownership/audit constraints and supports --allow-audit-update with optional --force override.\",\n ],\n },\n templates: {\n why: \"Saves, lists, and inspects reusable create option bundles for repeatable workflows.\",\n examples: [\n 'pm templates save triage-default --title \"Triage item\" --description \"...\" --type Task --status open --priority 2 --message \"Seed triage template\"',\n \"pm templates list\",\n \"pm templates show triage-default\",\n ],\n tips: [\n \"Template names are positional arguments (`pm templates save <name>` and `pm templates show <name>`), not --name flags.\",\n \"Combine templates with explicit create flags; explicit flags always override template defaults.\",\n ],\n },\n deps: {\n why: \"Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.\",\n examples: [\n \"pm deps pm-a1b2\",\n \"pm deps pm-a1b2 --format graph\",\n \"pm deps pm-a1b2 --max-depth 2 --collapse repeated --summary\",\n ],\n tips: [\"Use --summary for lightweight counts when full graph payloads are unnecessary.\"],\n },\n list: {\n why: \"Lists active items with deterministic filtering and ordering.\",\n examples: [\n \"pm list --limit 20\",\n \"pm list --type Task --priority 0 --tag release --assignee codex-agent\",\n \"pm list --compact --sort deadline --order asc\",\n \"pm list --fields id,title,parent,type --sort parent --order asc\",\n ],\n },\n \"list-all\": {\n why: \"Lists all item states (including terminal states) when you need full visibility.\",\n examples: [\"pm list-all --limit 50\", \"pm list-all --type Issue --include-body\"],\n },\n \"list-open\": {\n why: \"Shows work that is ready to claim and start.\",\n examples: [\"pm list-open --priority 0 --limit 10\"],\n },\n \"list-in-progress\": {\n why: \"Tracks active execution and owner progress.\",\n examples: [\"pm list-in-progress --assignee codex-agent --limit 20\"],\n },\n \"list-blocked\": {\n why: \"Surfaces blocked work that needs intervention.\",\n examples: [\"pm list-blocked --limit 20\"],\n },\n \"list-closed\": {\n why: \"Reviews completed work and closure outcomes.\",\n examples: [\"pm list-closed --limit 20 --type Task\"],\n },\n \"list-canceled\": {\n why: \"Audits intentionally discontinued work.\",\n examples: [\"pm list-canceled --limit 20\"],\n },\n \"list-draft\": {\n why: \"Finds incompletely defined items that need refinement before execution.\",\n examples: [\"pm list-draft --limit 20\"],\n },\n aggregate: {\n why: \"Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.\",\n examples: [\n \"pm aggregate --group-by parent,type --count\",\n \"pm aggregate --group-by type,status --count\",\n \"pm aggregate --group-by parent,type --count --status open --parent pm-feature01\",\n ],\n tips: [\"Current aggregate mode is grouped counts only, so pass --count explicitly.\"],\n },\n \"dedupe-audit\": {\n why: \"Audits potential duplicate items and emits deterministic merge suggestions before any mutation.\",\n examples: [\n \"pm dedupe-audit --mode title_exact\",\n \"pm dedupe-audit --mode title_fuzzy --threshold 0.8 --limit 20\",\n \"pm dedupe-audit --mode parent_scope --status open\",\n ],\n tips: [\"Use title_exact for strict collisions, title_fuzzy for near-duplicates, and parent_scope for child-level collisions.\"],\n },\n guide: {\n why: \"Routes local progressive-disclosure documentation so agents can fetch only the context they need.\",\n examples: [\n \"pm install guide-shell --project\",\n \"pm guide\",\n \"pm guide quickstart\",\n \"pm guide commands --depth standard\",\n \"pm guide skills --depth deep --format markdown\",\n \"pm guide release --json\",\n ],\n tips: [\n \"Use brief depth for minimal token footprint, standard for excerpted docs, and deep for full local document rendering.\",\n \"Use --list to force topic index output even when topic parsing is ambiguous.\",\n ],\n },\n calendar: {\n why: \"Provides deadline/reminder/event scheduling views for planning and coordination.\",\n examples: [\n \"pm calendar\",\n \"pm calendar --view agenda --from +0d --to +7d --assignee codex-agent\",\n \"pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events\",\n \"pm calendar --view month --tag release --format json\",\n ],\n tips: [\n \"Day/week/month views are anchored period windows; default mode clips the start to now unless --past or --full-period is set.\",\n \"--full-period applies only to day/week/month views; use --from/--to to bound agenda windows.\",\n ],\n },\n context: {\n why: \"Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.\",\n examples: [\n \"pm context\",\n \"pm ctx --depth standard --limit 10\",\n \"pm ctx --depth deep --assignee codex-agent\",\n \"pm ctx --section hierarchy --section progress --section blockers\",\n \"pm context --depth standard --activity-limit 20 --stale-threshold 14d\",\n \"pm context --from +0d --to +7d --format markdown --depth deep\",\n ],\n tips: [\n \"High-level focus contains Epics/Features and low-level focus contains Tasks/Issues/Chores/Decisions/Event/Reminder/Milestone/Meeting/Plan.\",\n \"When no open or in-progress work exists, blocked items are shown as fallback context.\",\n \"--depth brief (default) shows focus+agenda; standard adds hierarchy/activity/progress/workload; deep adds blockers/files/staleness/tests.\",\n \"--section overrides --depth and selects specific sections: hierarchy, activity, progress, blockers, files, workload, staleness, tests.\",\n \"Configure defaults via pm config project set context --default-depth standard --activity-limit 15.\",\n ],\n },\n search: {\n why: \"Finds relevant items by keyword, semantic, or hybrid retrieval modes.\",\n examples: [\n 'pm search \"lock stale retry\" --mode keyword --limit 10',\n 'pm search \"extension migration blockers\" --mode hybrid --type Task --priority 0',\n 'pm search \"Cross-Epic Realism Dependency Council\" --mode keyword --title-exact',\n ],\n tips: [\n \"Use --title-exact to require exact normalized title parity, or --phrase-exact to require full-phrase matches in item text fields.\",\n \"Use --include-linked when linked docs/files/tests should influence scoring.\",\n ],\n },\n reindex: {\n why: \"Rebuilds search artifacts after large changes to item corpus or provider/vector config.\",\n examples: [\"pm reindex --mode keyword\", \"pm reindex --mode hybrid --progress --json\"],\n tips: [\n \"Use --progress for non-interactive visibility during local embedding runs.\",\n \"JSON output includes semantic stale/unchanged/embed/upsert counts so agents can gate long reindex work without parsing stderr.\",\n ],\n },\n get: {\n why: \"Shows details for one item by ID, with optional lower-token projections for agent loops.\",\n examples: [\n \"pm get pm-a1b2\",\n \"pm get pm-a1b2 --depth brief --json\",\n \"pm get pm-a1b2 --fields id,title,status,parent,type --json\",\n ],\n tips: [\n \"Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.\",\n \"Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.\",\n \"JSON output shape is { item, body, linked, claim_state }; body is top-level (not item.body).\",\n ],\n },\n history: {\n why: \"Inspects item mutation timeline and audit trail.\",\n examples: [\"pm history pm-a1b2 --limit 20\", \"pm history pm-a1b2 --full --verify\"],\n },\n \"history-compact\": {\n why: \"Compacts long history streams into a synthetic checkpoint while preserving replay integrity.\",\n examples: [\n \"pm history-compact pm-a1b2 --dry-run\",\n \"pm history-compact pm-a1b2 --before 25 --author codex-agent --message \\\"Compact early history\\\"\",\n \"pm history-compact pm-a1b2 --before 2026-06-01T00:00:00.000Z\",\n ],\n },\n activity: {\n why: \"Reviews recent tracker-wide activity across items.\",\n examples: [\n \"pm activity --limit 50\",\n \"pm activity --full --id pm-a1b2 --limit 50\",\n \"pm activity --id pm-a1b2 --op update --author codex-agent --from -7d --to now\",\n \"pm activity --json --stream rows --limit 200\",\n ],\n tips: [\"Use --stream with --json for line-delimited automation output; --from is inclusive and --to is exclusive.\"],\n },\n restore: {\n why: \"Restores an item to a prior timestamp/version with history replay safety.\",\n examples: ['pm restore pm-a1b2 2026-04-01T00:00:00.000Z --author \"codex-agent\" --message \"Rollback to known-good state\"'],\n },\n close: {\n why: \"Transitions work to terminal closed state with explicit rationale.\",\n examples: [\n 'pm close pm-a1b2 \"All acceptance criteria met\" --author \"codex-agent\" --message \"Close after verification\"',\n 'pm close pm-a1b2 \"Done\" --validate-close',\n 'pm close pm-a1b2 \"Done\" --validate-close off',\n 'pm close pm-a1b2 \"Done\" --validate-close strict',\n ],\n },\n delete: {\n why: \"Removes an item while preserving history evidence and lock/ownership checks.\",\n examples: ['pm delete pm-a1b2 --author \"codex-agent\" --message \"Remove duplicate item\"'],\n },\n append: {\n why: \"Adds implementation notes to body without replacing existing content.\",\n examples: ['pm append pm-a1b2 --body \"Implemented retry with bounded backoff.\" --message \"Record implementation detail\"'],\n },\n comments: {\n why: \"Adds or reviews lightweight status updates linked to an item.\",\n examples: [\n 'pm comments pm-a1b2 \"Verified fix on Linux and macOS\"',\n 'pm comments pm-a1b2 --add \"Verified fix on Linux and macOS\"',\n 'printf \"%s\\\\n\" \"## Verification\" \"- linux pass\" \"- mac pass\" \| pm comments pm-a1b2 --stdin',\n 'pm comments pm-a1b2 --file docs/release-evidence.md --author \"codex-agent\"',\n 'pm comments pm-a1b2 --add \"text: verification note with commas, key-like words, and parser details\"',\n 'pm comments pm-a1b2 --add \"Follow-up needed after review\" --author \"codex-agent\" --force',\n \"pm comments pm-a1b2 --limit 10\",\n ],\n tips: [\n \"Use exactly one comment source at a time: positional [text], --add, --stdin, or --file.\",\n \"Use --force when adding comments to items currently assigned to a different owner.\",\n \"When --add payload resembles CSV-like key fragments (for example text=hello,scope:project), plain-text fallback is intentional; use explicit text=..., markdown text: ..., or stdin token - for structured intent.\",\n ],\n },\n \"comments-audit\": {\n why: \"Audits latest comments or full history rows across filtered item sets.\",\n examples: [\n \"pm comments-audit --status open --latest 1\",\n \"pm comments-audit --status open --latest 0\",\n \"pm comments-audit --parent pm-feature01 --tag governance --sprint sprint-12 --release vnext --priority 0\",\n \"pm comments-audit --full-history --limit 50\",\n ],\n tips: [\n \"Use either --latest or --full-history (not both). --latest 0 returns item summaries without comment rows. --limit is an alias for --limit-items.\",\n ],\n },\n notes: {\n why: \"Adds or reviews durable implementation notes linked to an item.\",\n examples: [\n 'pm notes pm-a1b2 --add \"Investigated parser edge case and documented fallback logic.\"',\n 'pm notes pm-a1b2 --add \"text: parser rationale with commas, colons, and key-like wording\"',\n 'pm notes pm-a1b2 --add \"Audit note\" --author \"reviewer\" --allow-audit-note',\n \"pm notes pm-a1b2 --limit 10\",\n ],\n tips: [\n \"Use --allow-audit-note for append-only non-owner audits; --allow-audit-comment remains supported as a legacy alias.\",\n \"CSV-like add payloads with extra key fragments are treated as plain text by design; use explicit text keys (text= or text:) when structured parsing is required.\",\n ],\n },\n learnings: {\n why: \"Adds or reviews post-implementation learnings for future work.\",\n examples: [\n 'pm learnings pm-a1b2 --add \"Avoid direct test-runner commands in linked tests; use sandbox runner.\"',\n 'pm learnings pm-a1b2 --add \"text: lesson with commas, key-like words, and punctuation-safe context\"',\n 'pm learnings pm-a1b2 --add \"Audit learning\" --author \"reviewer\" --allow-audit-learning',\n \"pm learnings pm-a1b2 --limit 10\",\n ],\n tips: [\n \"Use --allow-audit-learning for append-only non-owner audits; --allow-audit-comment remains supported as a legacy alias.\",\n \"If you intended structured parsing for a key-like payload, prefer explicit text=..., markdown text: ..., or stdin token -; ambiguous CSV-like forms intentionally remain plain text.\",\n ],\n },\n files: {\n why: \"Associates changed source files with tracker items for reproducibility.\",\n examples: [\n 'pm files pm-a1b2 --add \"path=src/cli/main.ts,note=help orchestration\"',\n \"pm files discover pm-a1b2\",\n 'pm files discover pm-a1b2 --apply --note \"discovered from item text\"',\n ],\n },\n docs: {\n why: \"Associates relevant documentation paths with tracker items.\",\n examples: ['pm docs pm-a1b2 --add \"path=README.md,note=user-facing command guidance\"'],\n },\n test: {\n why: \"Links test commands/paths and optionally executes them for one item.\",\n examples: [\n 'pm test pm-a1b2 --add \"command=node scripts/run-tests.mjs test -- tests/unit/output.spec.ts,timeout_seconds=2400\"',\n 'pm test pm-a1b2 --add \"command=pm list-all --type Task --limit 200,assert_stdout_contains=count:,assert_stdout_regex=count:\\\\s+\\\\d+\"',\n 'pm test pm-a1b2 --add \"command=pm list-all --type Task --limit 200,pm_context_mode=auto\"',\n \"pm test pm-a1b2 --run --timeout 2400 --env-set PORT=0 --env-clear PLAYWRIGHT_BASE_URL --shared-host-safe --pm-context tracker --fail-on-context-mismatch --fail-on-skipped\",\n \"pm test pm-a1b2 --run --timeout 2400 --pm-context auto\",\n \"pm test pm-a1b2 --run --background --timeout 2400 --progress\",\n ],\n },\n \"test-all\": {\n why: \"Runs linked tests in bulk for release/readiness sweeps.\",\n examples: [\n \"pm test-all --status in_progress --limit 5 --offset 10 --timeout 2400\",\n \"pm test-all --status closed --timeout 3600 --progress --env-set PORT=0 --shared-host-safe --fail-on-skipped\",\n \"pm test-all --status in_progress --pm-context tracker --fail-on-context-mismatch --require-assertions-for-pm\",\n \"pm test-all --status in_progress --pm-context auto --fail-on-context-mismatch\",\n \"pm test-all --status in_progress --background --timeout 3600\",\n ],\n },\n \"test-runs\": {\n why: \"Manages background linked-test runs with lifecycle controls and log/status inspection.\",\n examples: [\n \"pm test-runs list --status running --limit 20\",\n \"pm test-runs status tr-abc123\",\n \"pm test-runs logs tr-abc123 --stream stderr --tail 200\",\n \"pm test-runs stop tr-abc123\",\n \"pm test-runs resume tr-abc123\",\n ],\n },\n stats: {\n why: \"Reports tracker-level totals and distribution by type/status.\",\n examples: [\"pm stats\", \"pm stats --json\"],\n },\n telemetry: {\n why: \"Inspects and manages local telemetry queue/runtime state for observability diagnostics.\",\n examples: [\n \"pm telemetry status\",\n \"pm telemetry stats --limit 10\",\n \"pm telemetry flush\",\n \"pm telemetry clear\",\n ],\n },\n health: {\n why: \"Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.\",\n examples: [\n \"pm health\",\n \"pm health --check-only --summary --json\",\n \"pm health --brief --json\",\n \"pm health --no-refresh\",\n \"pm health --refresh-vectors\",\n ],\n },\n validate: {\n why:\n \"Runs standalone metadata, resolution, lifecycle (including dependency-cycle diagnostics), linked-file, linked-command reference, and history drift checks with default remediation hints for resolution gaps.\",\n examples: [\n \"pm validate\",\n \"pm validate --check-resolution --json\",\n \"pm validate --check-lifecycle --dependency-cycle-severity error\",\n \"pm validate --check-files --scan-mode tracked-all\",\n \"pm validate --check-files --scan-mode tracked-all-strict --include-pm-internals\",\n \"pm validate --check-command-references\",\n \"pm validate --check-resolution --fail-on-warn --json\",\n ],\n tips: [\"Resolution-gap warnings include default `pm update <id> ...` remediation hint templates in check details.\"],\n },\n gc: {\n why: \"Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.\",\n examples: [\"pm gc --dry-run\", \"pm gc\"],\n },\n claim: {\n why: \"Claims an item to signal active ownership and reduce conflicts.\",\n examples: [\n 'pm claim pm-a1b2 --author \"codex-agent\" --message \"Claim for implementation\"',\n 'pm claim pm-a1b2 --force --author \"codex-agent\" --message \"Take over terminal item\"',\n ],\n tips: [\"Claim takeover for non-terminal items does not require --force; --force is reserved for terminal/lock overrides.\"],\n },\n release: {\n why: \"Releases an active claim when paused, handed off, or completed.\",\n examples: [\n 'pm release pm-a1b2 --author \"codex-agent\" --message \"Release after closure\"',\n 'pm release pm-a1b2 --allow-audit-release --author \"reviewer\" --message \"Audit handoff release\"',\n ],\n tips: [\"Use --allow-audit-release for non-owner handoffs that only clear assignee metadata.\"],\n },\n \"start-task\": {\n why: \"Lifecycle alias that claims an item and sets status to in_progress.\",\n examples: ['pm start-task pm-a1b2 --author \"codex-agent\" --message \"Start implementation\"'],\n },\n \"pause-task\": {\n why: \"Lifecycle alias that sets status to open and releases active assignment.\",\n examples: ['pm pause-task pm-a1b2 --author \"codex-agent\" --message \"Pause for dependency unblock\"'],\n },\n \"close-task\": {\n why: \"Lifecycle alias that closes with reason text and clears assignment metadata.\",\n examples: ['pm close-task pm-a1b2 \"All acceptance criteria met\" --author \"codex-agent\" --message \"Close and handoff\"'],\n },\n completion: {\n why: \"Generates shell completion scripts for faster and more reliable command entry.\",\n examples: [\"pm completion bash\", \"pm completion zsh\", \"pm completion fish\", \"pm completion bash --eager-tags\"],\n tips: [\"Default scripts resolve tag suggestions lazily at completion time; use --eager-tags to embed current tags directly.\"],\n },\n contracts: {\n why: \"Exposes machine-readable CLI command and tool schema contracts for agent integrations.\",\n examples: [\n \"pm contracts\",\n \"pm contracts --command list --runtime-only\",\n \"pm contracts --command update --flags-only\",\n \"pm contracts --availability-only --runtime-only\",\n \"pm contracts --action create\",\n \"pm contracts --schema-only\",\n ],\n tips: [\"Use --command to narrow actions/schema to one CLI surface; combine with --flags-only or --availability-only for lighter payloads.\"],\n },\n};\n\nexport const ROOT_HELP_BUNDLE: HelpBundle = {\n why: \"Provides deterministic project management workflows for humans and coding agents.\",\n examples: [\n \"pm init\",\n \"pm install guide-shell --project\",\n \"pm list-open --limit 10\",\n 'pm create --title \"...\" --description \"...\" --type Task --status open --priority 1 --message \"...\" --create-mode progressive',\n ],\n tips: [\n \"Use <command> --help for command-specific guidance and examples.\",\n \"Install guide-shell before using pm guide for local docs and skills routing.\",\n \"Use --json for machine parsing and integration flows.\",\n \"Use --no-pager to force direct help output in CI and other non-interactive shells.\",\n ],\n};\n\nfunction resolveCanonicalHelpPath(commandPath: string \| undefined): string {\n const normalized = normalizeHelpCommandPath(commandPath ?? \"\");\n if (!normalized) {\n return \"\";\n }\n return HELP_PATH_ALIASES[normalized] ?? normalized;\n}\n\nexport function resolveHelpBundleForPath(commandPath: string \| undefined): HelpBundle {\n const canonicalPath = resolveCanonicalHelpPath(commandPath);\n if (!canonicalPath) {\n return ROOT_HELP_BUNDLE;\n }\n return HELP_BY_COMMAND_PATH[canonicalPath] ?? ROOT_HELP_BUNDLE;\n}\n\nexport function resolveHelpNarrative(commandPath: string \| undefined, detailMode: HelpDetailMode): HelpNarrative {\n const bundle = resolveHelpBundleForPath(commandPath);\n return {\n intent: bundle.why,\n examples: detailMode === \"detailed\" ? [...bundle.examples] : bundle.examples.length > 0 ? [bundle.examples[0]] : [],\n tips: detailMode === \"detailed\" ? [...(bundle.tips ?? [])] : [],\n detail_mode: detailMode,\n };\n}\n\nexport function attachRichHelpText(program: Command, argv: string[] = process.argv.slice(2)): void {\n const detailMode = resolveHelpDetailMode(argv);\n program.addHelpText(\"after\", renderHelpBundle(ROOT_HELP_BUNDLE, detailMode));\n for (const [commandPath, bundle] of Object.entries(HELP_BY_COMMAND_PATH)) {\n attachBundleByPath(program, commandPath, bundle, detailMode);\n }\n}\n"],"names":[],"mappings":"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","debugId":"ad4ec245-86cd-551a-814a-482b7a2442b8"}
1	+ {"version":3,"file":"help-content.js","sources":["cli/help-content.ts"],"sourceRoot":"/","sourcesContent":["import { Command } from \"commander\";\n\nexport interface HelpBundle {\n why: string;\n examples: string[];\n tips?: string[];\n}\n\nexport interface HelpNarrative {\n intent: string;\n examples: string[];\n tips: string[];\n detail_mode: HelpDetailMode;\n}\n\nexport type HelpDetailMode = \"compact\" \| \"detailed\";\n\nfunction renderCompactHelpBundle(bundle: HelpBundle): string {\n const lines: string[] = [\n \"\",\n \"Intent:\",\n ` ${bundle.why}`,\n ];\n if (bundle.examples.length > 0) {\n lines.push(\"\", \"Example:\");\n lines.push(` ${bundle.examples[0]}`);\n }\n lines.push(\"\", \"Need deeper rationale and more examples?\");\n lines.push(\" Re-run with --explain.\");\n return lines.join(\"\\n\");\n}\n\nfunction renderDetailedHelpBundle(bundle: HelpBundle): string {\n const lines: string[] = [\n \"\",\n \"Why use this command:\",\n ` ${bundle.why}`,\n \"\",\n \"Examples:\",\n ...bundle.examples.map((example) => ` ${example}`),\n ];\n if (bundle.tips && bundle.tips.length > 0) {\n lines.push(\"\", \"Tips:\");\n lines.push(...bundle.tips.map((tip) => ` - ${tip}`));\n }\n return lines.join(\"\\n\");\n}\n\nfunction renderHelpBundle(bundle: HelpBundle, detailMode: HelpDetailMode): string {\n if (detailMode === \"detailed\") {\n return renderDetailedHelpBundle(bundle);\n }\n return renderCompactHelpBundle(bundle);\n}\n\nexport function normalizeHelpCommandPath(commandPath: string): string {\n return commandPath\n .trim()\n .toLowerCase()\n .split(/\\s+/)\n .filter((part) => part.length > 0)\n .join(\" \");\n}\n\nconst HELP_PATH_ALIASES: Record<string, string> = {\n cal: \"calendar\",\n ctx: \"context\",\n};\n\nfunction findDirectChildCommand(parent: Command, name: string): Command \| null {\n return parent.commands.find((entry) => entry.name() === name) ?? null;\n}\n\nfunction findCommandByPath(root: Command, pathParts: string[]): Command \| null {\n let current: Command = root;\n for (const part of pathParts) {\n const next = findDirectChildCommand(current, part);\n if (!next) {\n return null;\n }\n current = next;\n }\n return current;\n}\n\nfunction attachBundleByPath(root: Command, commandPath: string, bundle: HelpBundle, detailMode: HelpDetailMode): void {\n const command = findCommandByPath(root, commandPath.split(\" \").filter((part) => part.length > 0));\n if (!command) {\n return;\n }\n command.addHelpText(\"after\", renderHelpBundle(bundle, detailMode));\n}\n\nexport function resolveHelpDetailMode(argv: string[]): HelpDetailMode {\n if (argv.includes(\"--explain\")) {\n return \"detailed\";\n }\n return \"compact\";\n}\n\nconst HELP_BY_COMMAND_PATH: Record<string, HelpBundle> = {\n init: {\n why: \"Bootstraps tracker storage and settings so all other commands can run safely.\",\n examples: [\n \"pm init\",\n \"pm init acme\",\n \"pm init --preset minimal\",\n \"pm init --agent-guidance add\",\n \"pm init --defaults --with-packages\",\n ],\n tips: [\n \"Run this once per repository before create/list/update commands.\",\n \"Use --preset for non-interactive automation; omit it in a TTY to use the setup wizard.\",\n \"Use --agent-guidance add to inject compact AGENTS/CLAUDE workflow guidance, or --agent-guidance status to inspect missing guidance without modifying files.\",\n \"Use --with-packages when agents need bundled commands such as calendar and templates available immediately.\",\n ],\n },\n config: {\n why: \"Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.\",\n examples: [\n 'pm config project get definition-of-done',\n 'pm config project set definition-of-done --criterion \"tests pass\"',\n \"pm config project set item-format --format toon\",\n \"pm config project set sprint-release-format-policy --policy strict_error\",\n \"pm config project set governance-preset --policy minimal\",\n \"pm config project set governance-ownership-enforcement --policy none\",\n \"pm config project set test-result-tracking --policy enabled\",\n \"pm config global set telemetry-tracking --policy disabled\",\n ],\n },\n extension: {\n why:\n \"Compatibility command for package-backed runtime extension lifecycle operations across project or global scope.\",\n examples: [\n \"pm install ./my-package --project\",\n \"pm install '' --project\",\n \"pm package doctor --project --detail summary\",\n \"pm package manage --global\",\n \"pm package activate sample-ext --project\",\n \"pm package deactivate sample-ext --project\",\n \"pm package uninstall sample-ext --global\",\n \"pm extension explore --project\",\n \"pm extension manage --global\",\n \"pm extension doctor --detail deep\",\n ],\n tips: [\n \"Prefer pm install and pm package in new user-facing automation.\",\n \"Use pm extension when maintaining existing extension-specific scripts or debugging the compatibility runtime directly.\",\n \"Bundled aliases beads and todos resolve to package-shipped extension sources.\",\n \"Use --gh/--github shorthand for GitHub sources and --ref to pin a branch, tag, or ref.\",\n \"Install updates settings activation state automatically unless extension allowlist mode is unchanged.\",\n \"Use --adopt for single-extension adoption and --adopt-all to bulk-register unmanaged installs as managed without reinstalling.\",\n \"Use --manage for concise triage summaries and remediation-oriented diagnostics alongside full extension details.\",\n \"Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads.\",\n ],\n },\n package: {\n why:\n \"Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.\",\n examples: [\n \"pm install npm:@scope/pm-package --project\",\n \"pm package install ./my-package --project\",\n \"pm package doctor --project --detail deep\",\n \"pm package manage --project --runtime-probe\",\n \"pm package activate sample-ext --project\",\n \"pm upgrade --packages-only --dry-run\",\n ],\n tips: [\n \"Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.\",\n \"Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.\",\n \"Use --dry-run before upgrade when automation needs a deterministic plan.\",\n ],\n },\n \"package init\": {\n why: \"Generates an installable starter pm package with package metadata and a root extension entrypoint.\",\n examples: [\n \"pm package init ./my-package\",\n \"pm install ./my-package --project\",\n \"pm package doctor --project --detail summary\",\n ],\n tips: [\n \"The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.\",\n \"Use package doctor after changes to verify activation, policy, and collision diagnostics.\",\n ],\n },\n \"package install\": {\n why: \"Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.\",\n examples: [\n \"pm package install ./my-package --project\",\n \"pm install npm:pm-changelog --project\",\n \"pm package install --github org/repo/packages/my-pm-package --ref main\",\n ],\n tips: [\n \"Prefer the top-level pm install alias in scripts when only installation is needed.\",\n \"Run pm package manage or pm package doctor after installing external packages.\",\n ],\n },\n \"package catalog\": {\n why: \"Lists bundled first-party package catalog metadata and compact field projections.\",\n examples: [\n \"pm package catalog --project\",\n \"pm package catalog --project --fields alias,installed,install_command\",\n \"pm package list --project --fields alias,package_name,category\",\n ],\n tips: [\n \"Use --fields for low-token package discovery in agent loops.\",\n \"External npm package discovery still belongs to npm search.\",\n ],\n },\n \"extension init\": {\n why: \"Generates an installable starter runtime extension with manifest and entrypoint files.\",\n examples: [\n \"pm extension init ./my-extension\",\n \"pm extension --install --project ./my-extension\",\n \"pm extension --doctor --project --detail summary\",\n ],\n tips: [\n \"Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold.\",\n ],\n },\n \"extension install\": {\n why: \"Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.\",\n examples: [\n \"pm extension install ./my-extension --project\",\n \"pm extension --install --project ./my-extension\",\n \"pm extension doctor --project --detail summary\",\n ],\n tips: [\"Prefer pm install or pm package install for new package-first automation.\"],\n },\n \"extension catalog\": {\n why: \"Compatibility view of bundled package catalog metadata.\",\n examples: [\n \"pm extension catalog --project\",\n \"pm extension catalog --project --fields alias,installed,install_command\",\n ],\n tips: [\"Prefer pm package catalog in new user-facing workflows.\"],\n },\n install: {\n why: \"Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.\",\n examples: [\n \"pm install '' --project\",\n \"pm install ./packages/pm-todos --project\",\n \"pm install npm:@scope/pm-package --global\",\n \"pm install --github org/repo/packages/my-pm-package --ref main\",\n ],\n tips: [\"Installed packages are recorded in managed state and can be inspected with pm package manage.\"],\n },\n upgrade: {\n why: \"Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.\",\n examples: [\n \"pm upgrade --dry-run\",\n \"pm upgrade --packages-only --project\",\n \"pm upgrade todos --dry-run\",\n \"pm upgrade --cli-only --repair\",\n \"pm upgrade --tag next --dry-run\",\n ],\n tips: [\n \"Omit target to include the CLI/SDK plus all managed packages in the selected scope.\",\n \"Pass a target to refresh one managed package by name, directory, package name, or source.\",\n \"Use --packages-only in repository automation when the global CLI should not be changed.\",\n ],\n },\n create: {\n why: \"Creates a new planning item with deterministic metadata and history.\",\n examples: [\n 'pm create --title \"Harden lock flow\" --description \"Improve stale lock handling\" --type Task --status open --priority 1 --message \"Create lock hardening task\" --create-mode progressive',\n 'pm create --title \"Weekly planning sync\" --description \"Recurring coordination meeting\" --type Meeting --schedule-preset lightweight',\n 'pm create --title \"Asset: Hero model\" --description \"Track playable model asset\" --type Asset --status open --priority 1 --message \"Create asset item\" --type-option category=Character --dep \"id=pm-epic01,kind=parent,author=codex-agent,created_at=now\" --comment \"author=codex-agent,created_at=now,text=Why this asset item exists.\" --note \"author=codex-agent,created_at=now,text=Initial implementation note.\" --learning \"author=codex-agent,created_at=now,text=Durable lesson placeholder.\" --file \"path=src/assets/hero.glb,note=tracked asset\" --test \"command=node scripts/run-tests.mjs test,timeout_seconds=240\" --doc \"path=README.md,note=asset docs\"',\n ],\n tips: [\n \"Use --schedule-preset lightweight for Reminder/Meeting/Event when you want minimal required create inputs.\",\n \"Use --type <value> to load type-aware policy guidance in --help output.\",\n ],\n },\n update: {\n why: \"Mutates existing item fields while preserving history and lock safety.\",\n examples: [\n 'pm update pm-a1b2 --status in_progress --message \"Start implementation\"',\n 'pm update pm-a1b2 --unset close-reason --message \"Clear stale close reason after reopen\"',\n 'pm update pm-a1b2 --unset assignee --deadline +2d --message \"Replan ownership and deadline\"',\n 'pm update pm-a1b2 --body \"Backfilled body text for legacy item\" --message \"Normalize missing body\"',\n ],\n tips: [\n 'Use \"pm close <ID> <TEXT>\" to close items instead of --status closed.',\n \"When reopening from closed to a non-terminal status, update clears stale close_reason unless explicitly set via --close-reason.\",\n 'Use \"pm append <ID> --body <text>\" for additive notes; use update --body to replace body content.',\n ],\n },\n \"update-many\": {\n why: \"Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.\",\n examples: [\n \"pm update-many --filter-status open --status in_progress --dry-run\",\n 'pm update-many --filter-tag wave:7 --replace-tests --test \"command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,timeout_seconds=240\"',\n 'pm update-many --filter-tag governance --reviewer maintainer-review --message \"Normalize reviewer metadata\"',\n \"pm update-many --rollback ckpt-abc123\",\n ],\n tips: [\n \"Use --dry-run first to inspect proposed changes before apply mode.\",\n \"Linked-array mutation flags mirror pm update semantics (for example --replace-tests, --clear-files, and repeatable --doc/--note seeds).\",\n \"Checkpoints are enabled by default for apply mode and can be restored with --rollback.\",\n ],\n },\n \"close-many\": {\n why: \"Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints — unlike update-many --status closed, which bypasses close validation.\",\n examples: [\n 'pm close-many --filter-sprint S-12 --reason \"Sprint S-12 acceptance criteria met\" --dry-run',\n 'pm close-many --filter-tag wave:7 --reason \"Superseded by redesign\" --validate-close warn',\n 'pm close-many --ids pm-a,pm-b,pm-c --reason \"Closed in batch\" --resolution \"Verified by integration suite\"',\n \"pm close-many --rollback close-many-20260604-abc123\",\n ],\n tips: [\n \"At least one filter (--filter-* or --ids) is required so close-many never matches every item.\",\n \"Already-terminal matches are skipped by default; pass --force to re-close them.\",\n \"Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.\",\n \"Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>.\",\n ],\n },\n normalize: {\n why:\n \"Scans items for low-signal lifecycle metadata drift, emits deterministic per-item plans, and optionally applies normalized metadata updates with update-style safety checks.\",\n examples: [\n \"pm normalize --dry-run\",\n \"pm normalize --filter-status in_progress --dry-run\",\n 'pm normalize --filter-status closed --apply --author \"codex-agent\" --message \"Normalize closure metadata\"',\n ],\n tips: [\n \"Dry-run mode is the default; pass --apply only after reviewing planned changes.\",\n \"Apply mode honors ownership/audit constraints and supports --allow-audit-update with optional --force override.\",\n ],\n },\n templates: {\n why: \"Saves, lists, and inspects reusable create option bundles for repeatable workflows.\",\n examples: [\n 'pm templates save triage-default --title \"Triage item\" --description \"...\" --type Task --status open --priority 2 --message \"Seed triage template\"',\n \"pm templates list\",\n \"pm templates show triage-default\",\n ],\n tips: [\n \"Template names are positional arguments (`pm templates save <name>` and `pm templates show <name>`), not --name flags.\",\n \"Combine templates with explicit create flags; explicit flags always override template defaults.\",\n ],\n },\n deps: {\n why: \"Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.\",\n examples: [\n \"pm deps pm-a1b2\",\n \"pm deps pm-a1b2 --format graph\",\n \"pm deps pm-a1b2 --max-depth 2 --collapse repeated --summary\",\n ],\n tips: [\"Use --summary for lightweight counts when full graph payloads are unnecessary.\"],\n },\n list: {\n why: \"Lists active items with deterministic filtering and ordering.\",\n examples: [\n \"pm list --limit 20\",\n \"pm list --type Task --priority 0 --tag release --assignee codex-agent\",\n \"pm list --compact --sort deadline --order asc\",\n \"pm list --fields id,title,parent,type --sort parent --order asc\",\n ],\n },\n \"list-all\": {\n why: \"Lists all item states (including terminal states) when you need full visibility.\",\n examples: [\"pm list-all --limit 50\", \"pm list-all --type Issue --include-body\"],\n },\n \"list-open\": {\n why: \"Shows work that is ready to claim and start.\",\n examples: [\"pm list-open --priority 0 --limit 10\"],\n },\n \"list-in-progress\": {\n why: \"Tracks active execution and owner progress.\",\n examples: [\"pm list-in-progress --assignee codex-agent --limit 20\"],\n },\n \"list-blocked\": {\n why: \"Surfaces blocked work that needs intervention.\",\n examples: [\"pm list-blocked --limit 20\"],\n },\n \"list-closed\": {\n why: \"Reviews completed work and closure outcomes.\",\n examples: [\"pm list-closed --limit 20 --type Task\"],\n },\n \"list-canceled\": {\n why: \"Audits intentionally discontinued work.\",\n examples: [\"pm list-canceled --limit 20\"],\n },\n \"list-draft\": {\n why: \"Finds incompletely defined items that need refinement before execution.\",\n examples: [\"pm list-draft --limit 20\"],\n },\n aggregate: {\n why: \"Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.\",\n examples: [\n \"pm aggregate --group-by parent,type --count\",\n \"pm aggregate --group-by type,status --count\",\n \"pm aggregate --group-by parent,type --count --status open --parent pm-feature01\",\n ],\n tips: [\"Current aggregate mode is grouped counts only, so pass --count explicitly.\"],\n },\n \"dedupe-audit\": {\n why: \"Audits potential duplicate items and emits deterministic merge suggestions before any mutation.\",\n examples: [\n \"pm dedupe-audit --mode title_exact\",\n \"pm dedupe-audit --mode title_fuzzy --threshold 0.8 --limit 20\",\n \"pm dedupe-audit --mode parent_scope --status open\",\n ],\n tips: [\"Use title_exact for strict collisions, title_fuzzy for near-duplicates, and parent_scope for child-level collisions.\"],\n },\n guide: {\n why: \"Routes local progressive-disclosure documentation so agents can fetch only the context they need.\",\n examples: [\n \"pm install guide-shell --project\",\n \"pm guide\",\n \"pm guide quickstart\",\n \"pm guide commands --depth standard\",\n \"pm guide skills --depth deep --format markdown\",\n \"pm guide release --json\",\n ],\n tips: [\n \"Use brief depth for minimal token footprint, standard for excerpted docs, and deep for full local document rendering.\",\n \"Use --list to force topic index output even when topic parsing is ambiguous.\",\n ],\n },\n calendar: {\n why: \"Provides deadline/reminder/event scheduling views for planning and coordination.\",\n examples: [\n \"pm calendar\",\n \"pm calendar --view agenda --from +0d --to +7d --assignee codex-agent\",\n \"pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events\",\n \"pm calendar --view month --tag release --format json\",\n ],\n tips: [\n \"Day/week/month views are anchored period windows; default mode clips the start to now unless --past or --full-period is set.\",\n \"--full-period applies only to day/week/month views; use --from/--to to bound agenda windows.\",\n ],\n },\n context: {\n why: \"Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.\",\n examples: [\n \"pm context\",\n \"pm ctx --depth standard --limit 10\",\n \"pm ctx --depth deep --assignee codex-agent\",\n \"pm ctx --section hierarchy --section progress --section blockers\",\n \"pm context --depth standard --activity-limit 20 --stale-threshold 14d\",\n \"pm context --from +0d --to +7d --format markdown --depth deep\",\n ],\n tips: [\n \"High-level focus contains Epics/Features and low-level focus contains Tasks/Issues/Chores/Decisions/Event/Reminder/Milestone/Meeting/Plan.\",\n \"When no open or in-progress work exists, blocked items are shown as fallback context.\",\n \"--depth brief (default) shows focus+agenda; standard adds hierarchy/activity/progress/workload; deep adds blockers/files/staleness/tests.\",\n \"--section overrides --depth and selects specific sections: hierarchy, activity, progress, blockers, files, workload, staleness, tests.\",\n \"Configure defaults via pm config project set context --default-depth standard --activity-limit 15.\",\n ],\n },\n search: {\n why: \"Finds relevant items by keyword, semantic, or hybrid retrieval modes.\",\n examples: [\n 'pm search \"lock stale retry\" --mode keyword --limit 10',\n 'pm search \"extension migration blockers\" --mode hybrid --type Task --priority 0',\n 'pm search \"Cross-Epic Realism Dependency Council\" --mode keyword --title-exact',\n ],\n tips: [\n \"Use --title-exact to require exact normalized title parity, or --phrase-exact to require full-phrase matches in item text fields.\",\n \"Use --include-linked when linked docs/files/tests should influence scoring.\",\n ],\n },\n reindex: {\n why: \"Rebuilds search artifacts after large changes to item corpus or provider/vector config.\",\n examples: [\"pm reindex --mode keyword\", \"pm reindex --mode hybrid --progress --json\"],\n tips: [\n \"Use --progress for non-interactive visibility during local embedding runs.\",\n \"JSON output includes semantic stale/unchanged/embed/upsert counts so agents can gate long reindex work without parsing stderr.\",\n ],\n },\n get: {\n why: \"Shows details for one item by ID, with optional lower-token projections for agent loops.\",\n examples: [\n \"pm get pm-a1b2\",\n \"pm get pm-a1b2 --depth brief --json\",\n \"pm get pm-a1b2 --fields id,title,status,parent,type --json\",\n ],\n tips: [\n \"Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.\",\n \"Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.\",\n \"JSON output shape is { item, body, linked, claim_state }; body is top-level (not item.body).\",\n ],\n },\n history: {\n why: \"Inspects item mutation timeline and audit trail.\",\n examples: [\"pm history pm-a1b2 --limit 20\", \"pm history pm-a1b2 --full --verify\"],\n },\n \"history-compact\": {\n why: \"Compacts long history streams into a synthetic checkpoint while preserving replay integrity.\",\n examples: [\n \"pm history-compact pm-a1b2 --dry-run\",\n \"pm history-compact pm-a1b2 --before 25 --author codex-agent --message \\\"Compact early history\\\"\",\n \"pm history-compact pm-a1b2 --before 2026-06-01T00:00:00.000Z\",\n ],\n },\n activity: {\n why: \"Reviews recent tracker-wide activity across items.\",\n examples: [\n \"pm activity --limit 50\",\n \"pm activity --full --id pm-a1b2 --limit 50\",\n \"pm activity --id pm-a1b2 --op update --author codex-agent --from -7d --to now\",\n \"pm activity --json --stream rows --limit 200\",\n ],\n tips: [\"Use --stream with --json for line-delimited automation output; --from is inclusive and --to is exclusive.\"],\n },\n restore: {\n why: \"Restores an item to a prior timestamp/version with history replay safety.\",\n examples: ['pm restore pm-a1b2 2026-04-01T00:00:00.000Z --author \"codex-agent\" --message \"Rollback to known-good state\"'],\n },\n close: {\n why: \"Transitions work to terminal closed state with explicit rationale.\",\n examples: [\n 'pm close pm-a1b2 \"All acceptance criteria met\" --author \"codex-agent\" --message \"Close after verification\"',\n 'pm close pm-a1b2 \"Done\" --validate-close',\n 'pm close pm-a1b2 \"Done\" --validate-close off',\n 'pm close pm-a1b2 \"Done\" --validate-close strict',\n ],\n },\n delete: {\n why: \"Removes an item while preserving history evidence and lock/ownership checks.\",\n examples: ['pm delete pm-a1b2 --author \"codex-agent\" --message \"Remove duplicate item\"'],\n },\n append: {\n why: \"Adds implementation notes to body without replacing existing content.\",\n examples: ['pm append pm-a1b2 --body \"Implemented retry with bounded backoff.\" --message \"Record implementation detail\"'],\n },\n comments: {\n why: \"Adds or reviews lightweight status updates linked to an item.\",\n examples: [\n 'pm comments pm-a1b2 \"Verified fix on Linux and macOS\"',\n 'pm comments pm-a1b2 --add \"Verified fix on Linux and macOS\"',\n 'printf \"%s\\\\n\" \"## Verification\" \"- linux pass\" \"- mac pass\" \| pm comments pm-a1b2 --stdin',\n 'pm comments pm-a1b2 --file docs/release-evidence.md --author \"codex-agent\"',\n 'pm comments pm-a1b2 --add \"text: verification note with commas, key-like words, and parser details\"',\n 'pm comments pm-a1b2 --add \"Follow-up needed after review\" --author \"codex-agent\" --force',\n \"pm comments pm-a1b2 --limit 10\",\n ],\n tips: [\n \"Use exactly one comment source at a time: positional [text], --add, --stdin, or --file.\",\n \"Use --force when adding comments to items currently assigned to a different owner.\",\n \"When --add payload resembles CSV-like key fragments (for example text=hello,scope:project), plain-text fallback is intentional; use explicit text=..., markdown text: ..., or stdin token - for structured intent.\",\n ],\n },\n \"comments-audit\": {\n why: \"Audits latest comments or full history rows across filtered item sets.\",\n examples: [\n \"pm comments-audit --status open --latest 1\",\n \"pm comments-audit --status open --latest 0\",\n \"pm comments-audit --parent pm-feature01 --tag governance --sprint sprint-12 --release vnext --priority 0\",\n \"pm comments-audit --full-history --limit 50\",\n ],\n tips: [\n \"Use either --latest or --full-history (not both). --latest 0 returns item summaries without comment rows. --limit is an alias for --limit-items.\",\n ],\n },\n notes: {\n why: \"Adds or reviews durable implementation notes linked to an item.\",\n examples: [\n 'pm notes pm-a1b2 --add \"Investigated parser edge case and documented fallback logic.\"',\n 'pm notes pm-a1b2 --add \"text: parser rationale with commas, colons, and key-like wording\"',\n 'pm notes pm-a1b2 --add \"Audit note\" --author \"reviewer\" --allow-audit-note',\n \"pm notes pm-a1b2 --limit 10\",\n ],\n tips: [\n \"Use --allow-audit-note for append-only non-owner audits; --allow-audit-comment remains supported as a legacy alias.\",\n \"CSV-like add payloads with extra key fragments are treated as plain text by design; use explicit text keys (text= or text:) when structured parsing is required.\",\n ],\n },\n learnings: {\n why: \"Adds or reviews post-implementation learnings for future work.\",\n examples: [\n 'pm learnings pm-a1b2 --add \"Avoid direct test-runner commands in linked tests; use sandbox runner.\"',\n 'pm learnings pm-a1b2 --add \"text: lesson with commas, key-like words, and punctuation-safe context\"',\n 'pm learnings pm-a1b2 --add \"Audit learning\" --author \"reviewer\" --allow-audit-learning',\n \"pm learnings pm-a1b2 --limit 10\",\n ],\n tips: [\n \"Use --allow-audit-learning for append-only non-owner audits; --allow-audit-comment remains supported as a legacy alias.\",\n \"If you intended structured parsing for a key-like payload, prefer explicit text=..., markdown text: ..., or stdin token -; ambiguous CSV-like forms intentionally remain plain text.\",\n ],\n },\n files: {\n why: \"Associates changed source files with tracker items for reproducibility.\",\n examples: [\n 'pm files pm-a1b2 --add \"path=src/cli/main.ts,note=help orchestration\"',\n 'pm files pm-a1b2 --add src/cli/main.ts --note \"help orchestration\"',\n \"pm files discover pm-a1b2\",\n 'pm files discover pm-a1b2 --apply --note \"discovered from item text\"',\n ],\n },\n docs: {\n why: \"Associates relevant documentation paths with tracker items.\",\n examples: [\n 'pm docs pm-a1b2 --add \"path=README.md,note=user-facing command guidance\"',\n 'pm docs pm-a1b2 --add README.md --note \"user-facing command guidance\"',\n ],\n },\n test: {\n why: \"Links test commands/paths and optionally executes them for one item.\",\n examples: [\n 'pm test pm-a1b2 --add \"command=node scripts/run-tests.mjs test -- tests/unit/output.spec.ts,timeout_seconds=2400\"',\n 'pm test pm-a1b2 --add \"command=pm list-all --type Task --limit 200,assert_stdout_contains=count:,assert_stdout_regex=count:\\\\s+\\\\d+\"',\n 'pm test pm-a1b2 --add \"command=pm list-all --type Task --limit 200,pm_context_mode=auto\"',\n \"pm test pm-a1b2 --run --timeout 2400 --env-set PORT=0 --env-clear PLAYWRIGHT_BASE_URL --shared-host-safe --pm-context tracker --fail-on-context-mismatch --fail-on-skipped\",\n \"pm test pm-a1b2 --run --timeout 2400 --pm-context auto\",\n \"pm test pm-a1b2 --run --background --timeout 2400 --progress\",\n ],\n },\n \"test-all\": {\n why: \"Runs linked tests in bulk for release/readiness sweeps.\",\n examples: [\n \"pm test-all --status in_progress --limit 5 --offset 10 --timeout 2400\",\n \"pm test-all --status closed --timeout 3600 --progress --env-set PORT=0 --shared-host-safe --fail-on-skipped\",\n \"pm test-all --status in_progress --pm-context tracker --fail-on-context-mismatch --require-assertions-for-pm\",\n \"pm test-all --status in_progress --pm-context auto --fail-on-context-mismatch\",\n \"pm test-all --status in_progress --background --timeout 3600\",\n ],\n },\n \"test-runs\": {\n why: \"Manages background linked-test runs with lifecycle controls and log/status inspection.\",\n examples: [\n \"pm test-runs list --status running --limit 20\",\n \"pm test-runs status tr-abc123\",\n \"pm test-runs logs tr-abc123 --stream stderr --tail 200\",\n \"pm test-runs stop tr-abc123\",\n \"pm test-runs resume tr-abc123\",\n ],\n },\n stats: {\n why: \"Reports tracker-level totals and distribution by type/status.\",\n examples: [\"pm stats\", \"pm stats --json\"],\n },\n telemetry: {\n why: \"Inspects and manages local telemetry queue/runtime state for observability diagnostics.\",\n examples: [\n \"pm telemetry status\",\n \"pm telemetry stats --limit 10\",\n \"pm telemetry flush\",\n \"pm telemetry clear\",\n ],\n },\n health: {\n why: \"Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.\",\n examples: [\n \"pm health\",\n \"pm health --check-only --summary --json\",\n \"pm health --brief --json\",\n \"pm health --no-refresh\",\n \"pm health --refresh-vectors\",\n ],\n },\n validate: {\n why:\n \"Runs standalone metadata, resolution, lifecycle (including dependency-cycle diagnostics), linked-file, linked-command reference, and history drift checks with default remediation hints for resolution gaps.\",\n examples: [\n \"pm validate\",\n \"pm validate --check-resolution --json\",\n \"pm validate --check-lifecycle --dependency-cycle-severity error\",\n \"pm validate --check-files --scan-mode tracked-all\",\n \"pm validate --check-files --scan-mode tracked-all-strict --include-pm-internals\",\n \"pm validate --check-command-references\",\n \"pm validate --check-resolution --fail-on-warn --json\",\n ],\n tips: [\"Resolution-gap warnings include default `pm update <id> ...` remediation hint templates in check details.\"],\n },\n gc: {\n why: \"Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.\",\n examples: [\"pm gc --dry-run\", \"pm gc\"],\n },\n claim: {\n why: \"Claims an item to signal active ownership and reduce conflicts.\",\n examples: [\n 'pm claim pm-a1b2 --author \"codex-agent\" --message \"Claim for implementation\"',\n 'pm claim pm-a1b2 --force --author \"codex-agent\" --message \"Take over terminal item\"',\n ],\n tips: [\"Claim takeover for non-terminal items does not require --force; --force is reserved for terminal/lock overrides.\"],\n },\n release: {\n why: \"Releases an active claim when paused, handed off, or completed.\",\n examples: [\n 'pm release pm-a1b2 --author \"codex-agent\" --message \"Release after closure\"',\n 'pm release pm-a1b2 --allow-audit-release --author \"reviewer\" --message \"Audit handoff release\"',\n ],\n tips: [\"Use --allow-audit-release for non-owner handoffs that only clear assignee metadata.\"],\n },\n \"start-task\": {\n why: \"Lifecycle alias that claims an item and sets status to in_progress.\",\n examples: ['pm start-task pm-a1b2 --author \"codex-agent\" --message \"Start implementation\"'],\n },\n \"pause-task\": {\n why: \"Lifecycle alias that sets status to open and releases active assignment.\",\n examples: ['pm pause-task pm-a1b2 --author \"codex-agent\" --message \"Pause for dependency unblock\"'],\n },\n \"close-task\": {\n why: \"Lifecycle alias that closes with reason text and clears assignment metadata.\",\n examples: ['pm close-task pm-a1b2 \"All acceptance criteria met\" --author \"codex-agent\" --message \"Close and handoff\"'],\n },\n completion: {\n why: \"Generates shell completion scripts for faster and more reliable command entry.\",\n examples: [\"pm completion bash\", \"pm completion zsh\", \"pm completion fish\", \"pm completion bash --eager-tags\"],\n tips: [\"Default scripts resolve tag suggestions lazily at completion time; use --eager-tags to embed current tags directly.\"],\n },\n contracts: {\n why: \"Exposes machine-readable CLI command and tool schema contracts for agent integrations.\",\n examples: [\n \"pm contracts\",\n \"pm contracts --command list --runtime-only\",\n \"pm contracts --command update --flags-only\",\n \"pm contracts --availability-only --runtime-only\",\n \"pm contracts --action create\",\n \"pm contracts --schema-only\",\n ],\n tips: [\"Use --command to narrow actions/schema to one CLI surface; combine with --flags-only or --availability-only for lighter payloads.\"],\n },\n};\n\nexport const ROOT_HELP_BUNDLE: HelpBundle = {\n why: \"Provides deterministic project management workflows for humans and coding agents.\",\n examples: [\n \"pm init\",\n \"pm install guide-shell --project\",\n \"pm list-open --limit 10\",\n 'pm create --title \"...\" --description \"...\" --type Task --status open --priority 1 --message \"...\" --create-mode progressive',\n ],\n tips: [\n \"Use <command> --help for command-specific guidance and examples.\",\n \"Install guide-shell before using pm guide for local docs and skills routing.\",\n \"Use --json for machine parsing and integration flows.\",\n \"Use --no-pager to force direct help output in CI and other non-interactive shells.\",\n ],\n};\n\nfunction resolveCanonicalHelpPath(commandPath: string \| undefined): string {\n const normalized = normalizeHelpCommandPath(commandPath ?? \"\");\n if (!normalized) {\n return \"\";\n }\n return HELP_PATH_ALIASES[normalized] ?? normalized;\n}\n\nexport function resolveHelpBundleForPath(commandPath: string \| undefined): HelpBundle {\n const canonicalPath = resolveCanonicalHelpPath(commandPath);\n if (!canonicalPath) {\n return ROOT_HELP_BUNDLE;\n }\n return HELP_BY_COMMAND_PATH[canonicalPath] ?? ROOT_HELP_BUNDLE;\n}\n\nexport function resolveHelpNarrative(commandPath: string \| undefined, detailMode: HelpDetailMode): HelpNarrative {\n const bundle = resolveHelpBundleForPath(commandPath);\n return {\n intent: bundle.why,\n examples: detailMode === \"detailed\" ? [...bundle.examples] : bundle.examples.length > 0 ? [bundle.examples[0]] : [],\n tips: detailMode === \"detailed\" ? [...(bundle.tips ?? [])] : [],\n detail_mode: detailMode,\n };\n}\n\nexport function attachRichHelpText(program: Command, argv: string[] = process.argv.slice(2)): void {\n const detailMode = resolveHelpDetailMode(argv);\n program.addHelpText(\"after\", renderHelpBundle(ROOT_HELP_BUNDLE, detailMode));\n for (const [commandPath, bundle] of Object.entries(HELP_BY_COMMAND_PATH)) {\n attachBundleByPath(program, commandPath, bundle, detailMode);\n }\n}\n"],"names":[],"mappings":"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","debugId":"a1d00ac8-e750-598f-a4ec-20581735dc84"}

package/dist/cli/register-mutation.js CHANGED Viewed

@@ -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]="f05f0b6a-38aa-501a-af20-476b9d77d383")}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]="07f90455-c9f8-5cb9-86fe-be98e72908cb")}catch(e){}}();
 import { Option } from "commander";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -642,7 +642,12 @@ export function registerMutationCommands(program) {
         .option("--claim", "Claim the plan on create for the author")
         .option("--from-search <value>", "Record the search query that led to plan creation")
         .option("--step-title <value>", "Step title for add-step / update-step")
-        .option("--step <value>", "Alias for --step-title")
+        // pm-6mit: --step is a Commander collect repeatable so `pm plan create
+        // --step A --step B` seeds ordered steps (previously a single-value alias
+        // for --step-title where the last value silently won). It must NOT be
+        // list:true in contracts — the bootstrap coalescer would comma-join values
+        // and corrupt titles containing commas.
+        .option("--step <value>", "Step title (repeatable on create: each --step appends an ordered step; elsewhere a single value aliases --step-title)", collect)
         .option("--step-body <value>", "Step body text")
         .option("--step-owner <value>", "Step owner")
         .option("--step-status <value>", "Step status: pending|in_progress|completed|blocked|skipped|superseded")
@@ -740,7 +745,10 @@ export function registerMutationCommands(program) {
             ["blocked_by", "blockedBy"],
             ["resume_context", "resumeContext"],
             ["from_search", "fromSearch"],
-            ["step", "stepTitle"],
+            // pm-6mit: "step" is no longer folded into stepTitle here — it is a
+            // first-class repeatable option normalized inside runPlan (create
+            // accumulates ordered steps; other subcommands accept a single value
+            // as a stepTitle alias).
             ["step_title", "stepTitle"],
             ["step_body", "stepBody"],
             ["step_owner", "stepOwner"],
@@ -835,25 +843,40 @@ export function registerMutationCommands(program) {
     });
     program
         .command("history-repair")
-        .argument("<id>", "Item id")
+        .argument("[id]", "Item id (omit with --all)")
+        .option("--all", "Scan every stream for drift and repair each drifted stream in one audited pass")
         .option("--dry-run", "Preview the re-anchor impact without writing the history file")
         .option("--author <value>", "Mutation author")
         .option("--message <value>", "Audit history message for the repair marker entry")
         .option("--force", "Force ownership/lock override")
-        .description("Re-anchor a drifted item history chain (recompute hashes, reconcile with the on-disk item) and record an audit marker.")
+        .description("Re-anchor a drifted item history chain (recompute hashes, reconcile with the on-disk item) and record an audit marker. Use --all to repair every drifted stream.")
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
-        const { runHistoryRepair } = await import("./commands/history-repair.js");
-        const result = await runHistoryRepair(id, {
+        const { runHistoryRepair, runHistoryRepairAll, assertHistoryRepairTarget } = await import("./commands/history-repair.js");
+        const all = options.all === true;
+        assertHistoryRepairTarget(id, all);
+        const repairOptions = {
             dryRun: options.dryRun === true,
             author: typeof options.author === "string" ? options.author : undefined,
             message: typeof options.message === "string" ? options.message : undefined,
             force: Boolean(options.force),
-        }, globalOptions);
+        };
         // history-repair only re-anchors the audit stream; item content is untouched,
         // so search caches do not need invalidation.
-        printResult(result, globalOptions);
+        if (all) {
+            const result = await runHistoryRepairAll(repairOptions, globalOptions);
+            printResult(result, globalOptions);
+            if (result.totals.failed > 0) {
+                // Per-stream failures are collected (one bad stream never aborts the
+                // pass) but must still fail the command for gating callers.
+                process.exitCode = EXIT_CODE.GENERIC_FAILURE;
+            }
+        }
+        else {
+            const result = await runHistoryRepair(id, repairOptions, globalOptions);
+            printResult(result, globalOptions);
+        }
         if (globalOptions.profile) {
             printError(`profile:command=history-repair took_ms=${Date.now() - startedAt}`);
         }
@@ -1146,6 +1169,7 @@ export function registerMutationCommands(program) {
         .option("--add-glob <value>", "Add linked file entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)", collect)
         .option("--remove <value>", "Remove linked file by path (path=<value>, path:<value>, plain path, or - for stdin)", collect)
         .option("--migrate <value>", "Migrate linked file paths in-place (from=<prefix>,to=<prefix>; repeatable)", collect)
+        .option("--note <value>", "Note attached to every link added by --add/--add-glob in this invocation (embedded note= wins)")
         .option("--list", "List linked files without mutating")
         .option("--append-stable", "Preserve existing linked-file order and append new links without full-array resorting")
         .option("--validate-paths", "Validate linked file paths for existence and file shape")
@@ -1166,6 +1190,7 @@ export function registerMutationCommands(program) {
             addGlob: addGlobValues,
             remove: removeValues,
             migrate: migrateValues,
+            note: typeof options.note === "string" ? options.note : undefined,
             list: Boolean(options.list),
             appendStable: Boolean(options.appendStable),
             validatePaths: Boolean(options.validatePaths),
@@ -1195,14 +1220,18 @@ export function registerMutationCommands(program) {
         .action(async (id, options, command) => {
         const globalOptions = getGlobalOptions(command);
         const startedAt = Date.now();
+        // Flags also declared on the parent files command (--note/--append-stable/
+        // --author/--message/--force) are consumed by the parent during parse, so
+        // merge ancestor opts back in (own options win) instead of reading opts() alone.
+        const mergedOptions = { ...command.optsWithGlobals(), ...options };
         const { runFilesDiscover } = await import("./commands/files.js");
         const result = await runFilesDiscover(id, {
-            apply: Boolean(options.apply),
-            note: typeof options.note === "string" ? options.note : undefined,
-            appendStable: Boolean(options.appendStable),
-            author: typeof options.author === "string" ? options.author : undefined,
-            message: typeof options.message === "string" ? options.message : undefined,
-            force: Boolean(options.force),
+            apply: Boolean(mergedOptions.apply),
+            note: typeof mergedOptions.note === "string" ? mergedOptions.note : undefined,
+            appendStable: Boolean(mergedOptions.appendStable),
+            author: typeof mergedOptions.author === "string" ? mergedOptions.author : undefined,
+            message: typeof mergedOptions.message === "string" ? mergedOptions.message : undefined,
+            force: Boolean(mergedOptions.force),
         }, globalOptions);
         if (result.changed) {
             await invalidateSearchCachesForMutation(globalOptions, result);
@@ -1219,6 +1248,7 @@ export function registerMutationCommands(program) {
         .option("--add-glob <value>", "Add linked doc entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)", collect)
         .option("--remove <value>", "Remove linked doc by path (path=<value>, path:<value>, plain path, or - for stdin)", collect)
         .option("--migrate <value>", "Migrate linked doc paths in-place (from=<prefix>,to=<prefix>; repeatable)", collect)
+        .option("--note <value>", "Note attached to every link added by --add/--add-glob in this invocation (embedded note= wins)")
         .option("--list", "List linked docs without mutating")
         .option("--validate-paths", "Validate linked doc paths for existence and file shape")
         .option("--audit", "Audit linked doc usage across all items for this item's linked paths")
@@ -1239,6 +1269,7 @@ export function registerMutationCommands(program) {
             addGlob: addGlobValues,
             remove: removeValues,
             migrate: migrateValues,
+            note: typeof options.note === "string" ? options.note : undefined,
             list: Boolean(options.list),
             validatePaths: Boolean(options.validatePaths),
             audit: Boolean(options.audit),
@@ -1279,4 +1310,4 @@ export function registerMutationCommands(program) {
     });
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=f05f0b6a-38aa-501a-af20-476b9d77d383
+//# debugId=07f90455-c9f8-5cb9-86fe-be98e72908cb