SDK lifecycle provenance and context-rich CLI primitives

Merged
UN
3mo ago
+1498-215

Outcome

This wide SDK/CLI bundle advances project management = context management across lifecycle provenance, storage, contracts, agent-facing context, mutation safety, dependency hygiene, and release generation.

Delivered

  • adds durable completed_at lifecycle timestamps plus SDK provenance and history-evidence backfill planning
  • preserves completion timestamps across create, update, close, copy, storage, MCP, CLI, structured mutations, public contracts, workspace memory, and release notes
  • exposes blocker IDs in compact context so agents retain actionable dependency provenance
  • makes activity relative ranges intuitive (7d / 1w mean look back), adds composable case-insensitive tag filters with unknown-tag diagnostics, and aligns --allow-missing-parent across CLI/SDK/MCP
  • makes mutation-guard configuration discoverable through typed SDK metadata
  • updates compatible Node types and duplication tooling, burns an obsolete ESLint suppression, and keeps incompatible major upgrades on their canonical PM lineages
  • updates the project-managed generator to released pm-changelog@2026.7.29; upstream support shipped in unbraind/pm-changelog#107

PM lineage

Verification

  • pnpm test:coverage — 6,497 tests, 100% statements / branches / functions / lines
  • pnpm lint, pnpm typecheck, pnpm contracts:check, pnpm quality:docs-skills, pnpm quality:context-eval
  • pnpm security:scan, pnpm audit --prod, pnpm dogfood:package-first, pnpm smoke:external-packages, pnpm smoke:npx
  • isolated packed consumer verified binary containment and npm/npx/bunx behavior plus all new CLI/SDK primitives
  • pm validate --check-resolution --check-history-drift — zero history drift across 2,183 items (291 pre-existing historical resolution warnings)
  • pm health --check-only — telemetry enabled, redacted, draining, and successfully flushed
  • GitHub dependency, code-scanning, and secret-scanning alert inventories are empty

Summary by cubic

Adds lifecycle-aware completion provenance and richer context primitives to the SDK and CLI to improve reporting accuracy and agent actionability. Reports, release notes, and automation now prefer actual completion time and expose blockers inline, while query UX and governance flags are more consistent.

  • New Features

    • Lifecycle provenance: add completed_at separate from closed_at; stamped on close/create-closed, preserved on copy; pm close/pm close-many/pm update accept --completed-at (ISO or relative). SDK adds resolveCompletionTimestamp and evidence-only planCompletedAtBackfill; release notes prefer completed_at; force re-close preserves completion unless overridden.
    • Context: low_level rows now include blocked and blocker_ids so agents see actionable blockers without a second command.
    • Query UX: activity --from accepts bare relative windows like 7d/1w; list --tag is repeatable and CSV-aware, case-insensitive, and warns on unknown tags.
    • Governance and config: update gains --allow-missing-parent (parity with create). Config help/results surface mutation-guard settings with canonical dashed keys and typed metadata (canonical_key, choices, min/max).
    • Workspace memory: exposes completion_time_sources counts to disclose actual-completion vs legacy fallbacks.
    • Contracts/docs updated across CLI/SDK/MCP; tests cover new flags and projections.

  • Dependencies

    • Bump @types/node and jscpd to latest compatible patches; keep incompatible majors deferred.
    • Update project-managed generator to pm-changelog@2026.7.29.
    • Tighten static quality gate and remove an obsolete ESLint suppression.

Summary by Sourcery

Track actual completion timestamps across the SDK and CLI, enrich context and list queries with blocker and tag metadata, and tighten governance and configuration visibility, while keeping dependencies and quality gates up to date.

New Features:

  • Introduce a dedicated completed_at lifecycle timestamp distinct from closed_at, with CLI and SDK support for setting, correcting, and propagating it across items and reports.
  • Expose blocked state and unresolved blocker IDs directly in context low-level focus rows and markdown output so agents can act on dependency provenance in a single view.
  • Allow relative-only activity windows like 7d/1w, and support composable, case-insensitive list tag filters with CSV and repeatable flag inputs plus unknown-tag diagnostics.
  • Add a shared allow-missing-parent escape hatch for update mutations under strict parent-reference validation, aligned across CLI, SDK, and MCP contracts.
  • Surface typed mutation-guard configuration metadata, including canonical kebab-case keys, summaries, choices, and numeric bounds, through config listing APIs and docs.
  • Extend workspace memory snapshots and selection results with completion-time source counts that disclose how often actual versus fallback timestamps are used.

Bug Fixes:

  • Ensure reopened items clear both closed_at and completed_at timestamps, and prevent completion corrections on non-terminal items.
  • Fix activity queries that previously returned empty results for bare relative from windows by treating them as backward-looking ranges.
  • Align list tag filtering behavior with tag mutation formats and warn when filters reference tags that are not present in the corpus.
  • Make MCP action option hoisting table-driven so unknown actions no longer receive unintended hoisting behavior.

Enhancements:

  • Refactor SDK lifecycle utilities into a dedicated module for resolving completion timestamps and planning evidence-backed backfills from history.
  • Improve CLI and SDK contracts for close and update actions with new completed-at and allow-missing-parent flags, and exclude these from bulk update-many where not supported.
  • Project completion-aware timestamps into release note generation and workspace memory to prefer actual completion time over legacy close or update times.
  • Clarify configuration CLI help and configuration docs to highlight mutation-guard policies and their preferred kebab-case spellings.
  • Hoist common MCP options via a centralized mapping to keep action schemas consistent and easier to extend.

Build:

  • Tighten the static quality gate by reducing the allowed ESLint suppression count and updating the release automation contracts accordingly.
  • Update development dependencies such as @types/node and jscpd to the latest compatible versions, and refresh the managed changelog generator version.