Publish canonical CLI grammar and typed alias contracts

Merged
UN
3mo ago
+9569-12661

Summary\n\n- publish an exhaustive 129-row CLI command-destination census with noun/verb grammar diagnostics and mandatory quality/release gates\n- consolidate lifecycle listing behind canonical and primitives while preserving hidden typed compatibility aliases\n- expose alias and grammar contracts consistently across the CLI, SDK, MCP discovery, completions, configuration, generated catalogs, and documentation\n- tighten agent-context token baselines and add negative controls, exact coverage, package, dogfood, security, and manual acceptance evidence\n- record dependency, GitHub, Sentry, and changelog governance through the canonical PM lineage\n\n## PM items\n\n- pm-pbyu\n- pm-yy8rmx\n- pm-wt43zj\n- pm-0z7n\n- pm-pfqi\n\n## Verification\n\n- Already up to date

Done in 618ms using pnpm v11.10.0
[ELIFECYCLE] Command failed with exit code 1. (all implementation, 100% coverage, quality, security, package, dogfood, PM assurance, changelog, and Sentry gates passed; Greptile provider gate reported its free quota exhausted)\n- exact coverage: 51,814 statements, 40,887 branches, 11,284 functions, and 52,908 lines at 100%\n- manual packaged CLI acceptance in an isolated temporary project\n- [WARN] POST https://registry.npmjs.org/-/npm/v1/security/advisories/bulk error (ETIMEDOUT). Will retry in 10 seconds. 2 retries left.
No known vulnerabilities found: zero vulnerabilities\n- GitHub issue-to-PM linkage inventory: all 498 issues linked; no open dependency, code-scanning, or secret-scanning alerts\n- pm-changelog 2026.8.17 generated the deterministic changelog from 2,135 closed items\n- Sentry high/critical gate: zero unresolved issues after confirming PM-CLI-27 had no recurrence after its main-branch fix\n\n## Compatibility\n\nDeprecated list aliases remain executable but hidden from default discovery. A one-line migration hint is enabled by default and can be disabled with .

Summary by Sourcery

Adopt a canonical noun–verb CLI grammar and consolidate lifecycle list commands behind typed, discoverable contracts while preserving backward-compatible aliases.

New Features:

  • Publish machine-readable noun–verb grammar, command-destination, and typed alias contracts across the CLI, SDK, MCP, completions, and runtime contract surfaces.
  • Consolidate lifecycle listing under pm list with status filters and --all, while retaining deprecated list-* commands as executable hidden aliases with migration hints.

Bug Fixes:

  • Remove the ambiguous pm list --all failure and align list behavior and schemas across CLI, SDK, MCP, completions, and documentation.

Enhancements:

  • Add a fail-closed grammar and MCP parity gate covering destination census completeness, alias targets, discoverable actions, and visible command-surface growth.
  • Add configurable deprecation hints through the ux.deprecation_hints setting and expose canonical versus deprecated action inventories.
  • Update user guidance, generated contract projections, token-surface baselines, and compatibility coverage for the canonical command model.

Build:

  • Add the command grammar gate to static quality checks and provide a dedicated command-grammar quality script.

Documentation:

  • Document the accepted noun–verb grammar, destination census, compatibility policy, and list-command migration guidance.
  • Update command usage examples and agent onboarding documentation to use canonical list filters.

Tests:

  • Add unit and integration coverage for grammar validation, alias compatibility, list routing, hidden discovery, MCP parity, settings, completions, and packaged CLI behavior.

Chores:

  • Refresh generated contracts, baselines, governance records, and changelog metadata for the new grammar and alias policy.

Summary by cubic

Publishes the canonical noun–verb CLI grammar and typed alias contracts, consolidates list variants behind --status/--all, and removes the pm list --all ambiguity. Previously list-open/in-progress/... were top-level; now pm list defaults to active items, --status selects lifecycle classes, --all includes every status, and legacy list-* spellings run as hidden typed aliases with a one-line migration hint.

  • Enforces grammar conformance via src/sdk/cli-contracts/grammar-contracts.ts and scripts/release/command-grammar-gate.mjs; excludes hidden aliases from visible accounting; distinguishes core vs. conditional destinations; requires keep-as-is reasons; fails on noun/verb drift and missing alias targets; also fails when core token baselines disappear and bounds grammar discovery subprocess resources.
  • Publishes PM_COMMAND_ALIAS_CONTRACTS, resolvePmCommandAlias, and renderPmCommandAliasMigrationHint; hides deprecated aliases from help, completions (Zsh/Fish parity), contracts, and MCP discovery; exposes PM_DISCOVERABLE_TOOL_ACTIONS and PM_DEPRECATED_TOOL_ACTIONS; preserves contracts when a deprecated action is explicitly requested; enforces MCP action and narrow-tool parity.
  • Canonicalizes list filters: adds --status and --all; removes the ambiguous_list_all error and code; fixed-status compatibility actions and schemas omit lifecycle selectors; updates tool schemas, completions, docs, and tests.
  • Adds optional ux.deprecation_hints (default true) to control the once-per-invocation alias hint and preserves SDK source compatibility when unset.
  • Documents the accepted grammar and destination census in docs/CLI_GRAMMAR.md.

Migration

  • Replace list-* commands with pm list --status <open|in_progress|blocked|closed|canceled|draft>; use pm list --all for all statuses.
  • Suppress alias migration hints: pm config set ux.deprecation_hints=false.
  • MCP clients should enumerate actions from PM_DISCOVERABLE_TOOL_ACTIONS; deprecated actions remain executable but are not advertised.