fix(health): let an explicit --summary or --brief project a --full run instead of being dropped

Merged
UN
6d ago
+259-26

Why

Fixes #1670. pm health --full --summary drops --summary without saying so. In either flag order the output is byte-identical to --full alone: 15,704 B against 636 B for --summary on a one-item tracker. Nothing in the output reports the omission. The fleet's strict gates call exactly this combination to "run everything, read little".

What changes

For health, --full is first a check-scope flag. It overrides the --check-only fast path and the skip flags, so the slow integrity, drift and vectorization checks run. The flags now compose instead of competing:

  • --full decides which checks run.
  • An explicit --summary, otherwise an explicit --brief, decides the projection. --full alone still returns complete details.
  • --strict-exit implies the summary only when --full is absent, so --strict-exit --full keeps its documented complete output.
  • The behaviour is the same in the CLI, PmClient.health and MCP action dispatch. The MCP default (summary when no projection flag is given) is unchanged.

list, graph and deps still refuse --summary/--brief with --full, because there --full is purely a projection. A refusal for health would break fleet gates that already pass both flags. docs/OUTPUT_PROJECTION_CONTRACTS.md records this difference. The --summary and --full help states the precedence within the ratcheted 485-token help budget.

Evidence

  • tests/integration/cli/health-projection-precedence.integration.spec.ts runs on one tracker:
    • --full --summary and --summary --full both return mode: summary with omitted_checks: [] and the same check names as --full.
    • --check-only --summary omits integrity, history_drift and vectorization, while --check-only --full --summary runs them.
    • --full --brief is brief, --strict-exit --full is complete and --strict-exit is summary.
    • The SDK client and MCP runAction match.
  • register-commands.spec.ts covers the CLI mapping, and health-check-only-contract.spec.ts covers the projection and skip-policy precedence.
  • Negative control: reverting the three source edits fails five assertions.
  • Full suite: 12,072 tests passed, exact coverage 100/100/100/100. Flag-lexicon, command-grammar and contract snapshots are current. The tracker assurances pass, with prose-edge-gaps at 1233.

Tracker: pm-gh1670. This PR also closes pm-ofllco, the release-preflight tranche of pm-998juj merged in #1672, so the next release notes carry it. It records the pm-gh1663 re-reproduction on main as well.

Summary by Sourcery

Make health check scope and output projection compose correctly so full runs can return explicitly requested compact output.

Bug Fixes:

  • Fix health output precedence so explicit --summary or --brief is honored when combined with --full, while --full still runs the complete health check set.
  • Preserve complete output for --strict-exit --full while retaining summary behavior for --strict-exit without --full.
  • Apply the updated health flag behavior consistently across the CLI, SDK, and MCP interfaces.

Enhancements:

  • Document the distinct health flag precedence and update CLI help and SDK option descriptions accordingly.

Documentation:

  • Document that health treats --full as a check-scope option, unlike projection-only commands such as list, graph, and deps.

Tests:

  • Add coverage for health projection precedence, check scope, strict-exit behavior, and CLI, SDK, and MCP consistency.

Chores:

  • Update release tracking and changelog entries for the health fix and release-preflight work.

Summary by cubic

Fixes pm health so an explicit --summary or --brief projects a --full run, instead of --full silently winning and dropping the summary flag. pm health --full --summary previously emitted the full 15,704-byte output in either flag order with no receipt, byte-identical to --full alone.

For health, --full now widens the check scope (every check runs, overriding the --check-only fast path and skip flags), while an explicit --summary or --brief selects the projection. --full alone still returns complete details, and --strict-exit implies the summary only when --full is absent. The behavior matches across the CLI, SDK client, and MCP dispatch. list, graph, and deps still refuse the combination because there --full is purely a projection; a refusal for health would break existing fleet gates that already run pm health --full --summary. The flag help and RunHealthOptions docstrings now state the precedence, with the docstring-quality baseline lowered accordingly.