SDK assurance: measurements, assertions, lifecycle gates, and durable verdicts

Merged
UN
3mo ago
+7059-233

Summary

  • add persisted SDK-first assurance measurements over items, typed dependencies, graph analytics, validate, health, history, links, extension providers, and derived arithmetic with bounded compute-cost receipts
  • add assertions with explicit polarity, scope, lifetime, enforcement, negative controls, typed ownership, and Decision-authorized weakening
  • add trigger-bound gates and immutable workspace verdicts across the core CLI, public SDK, PmClient, generic action runner, and MCP
  • publish complete runtime, tool-schema, generated agent-surface, public SDK, and token-budget contracts
  • refresh policy-aged ESLint and Node type dependencies and regenerate the PM changelog
  • canonically track and backlink GitHub reports #969, #970, and #971 without claiming them as implemented

PM lineage

New open report lineages:

Verification

  • 481 test files and 7,201 tests pass
  • exact 100% statements, branches, functions, and lines: 51,922 / 38,124 / 10,679 / 50,153
  • strict ESLint, zero jscpd clones, 100% docstring gates, tracker measurement ratchets, contract snapshots, SDK public-surface snapshot, docs links, and 92 token surfaces pass
  • packed npm install plus direct CLI, npx, and bunx acceptance pass in a temporary project
  • 88-command package-first dogfood passes
  • pnpm audit reports no known vulnerabilities; GitHub dependency, code, and secret alert inventories are empty
  • changelog generated and checked with pm-changelog 2026.8.9
  • the local aggregate release pipeline passes through packed smoke and dogfood, then correctly stops because hosted DeepScan evidence cannot exist until this exact PR head is pushed; hosted analysis remains mandatory here

Summary by Sourcery

Introduce a unified SDK-owned project assurance system with measurements, assertions, lifecycle gates, and durable verdict history, exposed consistently via CLI, SDK, MCP, and runtime contracts.

New Features:

  • Add a declarative assurance model for measurements, assertions, and gates with bounded-cost evaluation and durable verdict recording.
  • Expose a new assurance action across CLI, PmClient, MCP, and contracts, including flag/schema support and positional/flag mappings.
  • Provide workspace-bound assurance runtime helpers that source data from items, history, graph, validate, health, and pluggable providers.
  • Document the project assurance primitives and expose new governance APIs on the public SDK surface.

Enhancements:

  • Extend tool-parameter schemas, enums, and contracts with assurance-specific fields, triggers, and schema-version bumps.
  • Propagate global CLI flag mappings and update action-schema parity tests for the new assurance command.
  • Export history-reading primitives to support durable verdict queries from the SDK.

Build:

  • Update pnpm lockfile and related baselines to reflect refreshed dependencies.

Documentation:

  • Add a dedicated Project Assurance Primitives guide and update the docs index with the new document.
  • Regenerate the generated agent command surface and related documentation baselines.

Tests:

  • Add comprehensive unit, integration, and CLI tests for assurance semantics, runtime bindings, transport normalization, and schema parity.
  • Update fixtures, contract snapshots, token-surface, and SDK public-surface baselines to cover the new assurance APIs.

Chores:

  • Track new open report lineages for projection cost, row-contract cost, and preflight health parity in the PM agents history and issues.
  • Refresh ESLint and @types/node development dependencies and update the changelog accordingly.

Summary by cubic

Adds SDK-owned assurance primitives and a new assurance command across CLI, SDK, PmClient, and MCP with durable verdict history. Hardens contracts, switches the hosted gate registry to stable workflow job IDs, refreshes eslint to 10.8.1 and @types/node to 26.2.0, and parallelizes gate context reads to speed up gate evaluation.

  • New Features

    • Measurements with composable sources (items/dependencies/graph/validate/health/history/links/provider), derived arithmetic, and compute-cost receipts.
    • Assertions with polarity, scope, lifetime, enforcement, required negative controls, typed ownership, and weakening detection.
    • Gates bound to lifecycle triggers; dry-run or recorded runs produce one verdict document and append immutable verdict entries.
    • CLI: assurance command (list, show, put, remove, run, verdicts) with shared flag/schema contracts; SDK and PmClient.assurance(...) route through one normalized action; docs in docs/ASSURANCE.md.
    • Performance: parallelized registry snapshot and workspace context reads before gate evaluation.

  • Bug Fixes

    • Strict kind-specific JSON Schemas for measurement/assertion/gate definitions, explicit terminal Decision authorization, and shared reference integrity.
    • Memoized and bounded evaluation with capped newest verdict reads; typed registry recovery and assurance_registry_invalid error guidance.
    • Public transport types and CLI/MCP parity improvements, including global flag mapping for --pm-path.
    • Hosted gate registry now inventories stable workflow job identities; updated inventory script, contracts, docs, and tests.
    • Added concurrency regression coverage for gate evaluation.