feat(cli,sdk): land the agent-UX stack — same-command corrections, terminal no-ops, bounded pm next, lean refusals, ranking policy

Merged
UN
2d ago
+4747-875

This PR now lands the whole stacked agent-UX tranche on main in one CI cycle. It contains every commit of #1635 and #1637, both of which were reviewed on their own PRs, plus the pm next ranking-policy change (GH-1618) and the fixes from four CodeRabbit review rounds. GitHub marks #1635 and #1637 merged when this lands. The individual descriptions on those PRs stay as the detailed record.

Tranche 1 — same-command corrections and bounded receipts (from #1635)

  • Contract-derived completeness corrections for read refusals (GH-1626).
  • Comma-list --unset on create / update / update many, with per-field validation (GH-1633). Review rounds then fixed four things:
    • update many plans aliased runtime fields under their stored key (gh-url → github_url).
    • Fields declared only for update_many resolve under the bulk scope.
    • Repeated --unset occurrences are no longer joined by bootstrap: the flag is declared repeatable, not list.
    • schema add-field refuses comma keys.
  • Bounded selective pm test receipts (GH-1630). restore_with is shell-quoted through renderPmCommand, and keeps --no-extensions and a tracker chosen by PM_PATH (blank --path falls through, as in resolvePmRoot).
  • Lean linked-test receipts for quiet successes (pm-covpax). They keep mismatch_detected and trusted, and the hint no longer tells callers to rerun, because a rerun repeats mutating flags.
  • Dash-leading values in unknown-option recovery (pm-stq61b) and the text-refusal overflow ladder (pm-4oc353).
  • New defect found in review, pm-8xgg7i: pm close cleared assignee but left claim_principal, so closed claimed items kept an active owner. Closure now clears both, and the five affected tracker items were released through the CLI.
  • Registry advisories GHSA-mrwp-f3q8-3g9p (follow-redirects) and GHSA-g3hv-75wg-m249 (minimatch) are cleared through pnpm-workspace.yaml overrides (pm-irviv0). This turns main's static gate green again. The recorded negative control reproduces the failure on the pre-fix commit and checks both advisory ids.

Tranche 2 — terminal no-ops, bounded pm next, lean refusals (from #1637)

  • Identical terminal updates keep closed_at / updated_at (GH-1628). Review rounds added two cases:
    • A blank reason under governance.require_close_reason goes to the refusing close route.
    • An item reopened concurrently before the field write is handed to the closure writer instead of being reported unchanged.
  • pm next discloses the whole response under its ceiling. filters.token_budget is null unless requested, and null columns are encoded by position (GH-1627).
  • Lean refusals keep a code-specific why, filter generic examples per entry (withoutGenericRefusalExamples, which replaces the unreleased isGenericRefusalExamples), and report the claim holder as typed fields. claim_source is unknown when history cannot prove the origin (GH-1610).

Tranche 3 — pm next ranking policy (GH-1618)

  • The ready queue is ordered under a declared policy: context.next_ranking_policy / NextOptions.rankingPolicy. The default is priority_floor, so priority tiers bound relevance and an hourly automation log can no longer outrank ready P0 work. weighted keeps the blended order.
  • filters.ranking_policy and the recommendation reasons disclose any disagreement between policy and relevance.
  • The pure ranking helpers live in src/sdk/query/next-ranking-policy.ts, so the published ./sdk/query surface is unchanged. The refusal for an unknown policy stays in next.ts, so the error catalog names the real command.

Follow-ups filed, not in this PR

  • pm-kjoudp: recovery commands rendered on Windows are not paste-safe in PowerShell ($(...) and backticks expand inside the CommandLineToArgvW double quotes). This needs one shell-dialect decision across all 41 call sites of quoteCommandArg.

Validation

  • Full static chain run locally on this head (everything in pnpm quality:static except mutation testing): 0 failures. This covers dependency advisories, docstrings, exports, ESLint, duplicates, contracts / error-catalog / capability-surface / SDK-surface snapshots, the package-boundary, grammar, flag and refusal gates, and the tracker-context-quality, graph-composition and record-integrity assurance runs.
  • The affected suites pass locally. Every behavioural fix has a regression test that fails against the previous source; the negative controls are recorded in the tracker.
  • CHANGELOG.md is regenerated from closed items, with no hand edits.

Closes #1626
Closes #1633
Closes #1630
Closes #1628
Closes #1627
Closes #1610
Closes #1618
Closes #1636

Summary by Sourcery

Improve agent-facing CLI and SDK workflows with bounded outputs, safer corrections, deterministic next-work ranking, and more actionable refusals.

New Features:

  • Add configurable pm next ranking policies with priority-floor ordering by default and blended weighted ordering as an option.
  • Expose structured ownership details in claim refusals and support lean refusal output across text and JSON surfaces.
  • Bound complete pm next responses while preserving lossless compact table encoding and explicit budget receipts.

Bug Fixes:

  • Preserve terminal timestamps and history for repeated identical close updates, including concurrent reopen handling.
  • Clear all claim ownership fields when closing items.
  • Correct repeated --unset parsing, bulk field resolution, tracker-path fallback, and dependency advisory overrides.

Enhancements:

  • Support comma-separated unset fields with per-field validation across create and update commands.
  • Improve selective test receipts and compact successful linked-test output.
  • Add policy disagreement explanations and typed claim-holder evidence to agent-facing responses.

Build:

  • Apply pnpm dependency overrides to resolve follow-redirects and minimatch security advisories.

Documentation:

  • Document pm next budgets, ranking policies, lean refusals, structured claim context, and terminal update semantics.

Tests:

  • Add regression coverage for ranking policies, bounded next responses, lean refusals, terminal no-ops, ownership cleanup, compact table encoding, and mutation behavior.

Chores:

  • Regenerate the changelog and update generated SDK and contract surfaces.