Make SDK context integrity durable across clones

Merged
UN
3mo ago
+894-141

Summary

This broad SDK/CLI tranche makes context-integrity evidence durable, version-safe, observable, and deterministic:

  • version the managed merge-driver fence so older clients cannot silently rewrite a newer fence during unrelated commands
  • persist hash-only merge-decision evidence in the tracked project store while retaining raw recovery values only in clone-local Git state
  • expose an explicit not_configured provenance outcome distinct from attempted resolver failures
  • scan immutable history with bounded reads for privacy-safe invalid provenance value classes
  • isolate shared foreign AI_AGENT signals without hiding dedicated same-harness resolver inputs
  • refresh the public SDK surface, health vector documentation, merge-safety guidance, tests, and generated changelog

Why

Project management is context management. Merge decisions and provenance are part of the durable context graph: they must survive clone boundaries, remain understandable across client versions, distinguish absence from failure, and never leak host-specific or raw private values.

PM lineage

Verification

  • node scripts/run-tests.mjs coverage: 464 files, 7,100 tests, exact 100/100/100/100
  • pnpm lint: ESLint, zero duplicate clones, and full static-quality pipeline passed
  • pnpm quality:static: SDK parity/snapshot, docstring, package boundary, surface replication, token/context, registry, and performance gates passed
  • pnpm audit --audit-level high: no known vulnerabilities
  • pnpm security:scan: no credential-like secrets
  • pm health --check-only, history drift, storage integrity, and dry-run merge reconciliation passed
  • latest pm-changelog@2026.8.7 generated and verified CHANGELOG.md
  • packed tarball installed in an isolated temporary consumer; init/create/comment/get/health/validate/storage/history and clean Git round-trip passed

Fixes #921
Fixes #922
Fixes #948

Summary by Sourcery

Persist privacy-safe merge decision receipts in tracker storage and make merge fences and provenance health checks durable and version-safe across clones.

New Features:

  • Track merge decision receipts in a durable merge-receipts store within the project tracker, preserving hash-only decision evidence across clones.
  • Expose provenance resolver health findings for invalid legacy value classes as aggregate, privacy-safe diagnostics.
  • Support a new not_configured provenance outcome to distinguish missing resolvers from unavailable harness signals.
  • Version the managed Git merge-driver fence so legacy pm-cli releases cannot rewrite the current contract during routine commands.

Bug Fixes:

  • Ensure provenance health and storage checks ignore foreign AI_AGENT signals and only treat harness-specific inputs as attempted resolver probes.
  • Prevent sandboxed and legacy harness environments from recording out-of-domain boolean and single-digit provenance values without detection.
  • Make merge-decision receipts visible in fresh clones and CI via durable hash-only summaries while keeping raw values confined to clone-local Git state.
  • Avoid legacy init and merge installers silently rewriting the tracked merge-driver fence under version skew.

Enhancements:

  • Unify merge receipt listing to deduplicate local and durable evidence while reporting availability of recoverable values.
  • Extend health and validation storage checks to surface provenance resolver outcomes and invalid-value aggregates without leaking raw history.
  • Refine agent identity diagnostics and test harness utilities to isolate shared environment signals and keep SDK behavior deterministic across environments.

Documentation:

  • Document durable merge decision receipts, privacy-safe sidecars, and provenance value domain scanning in the merge safety and context integrity guides.
  • Refresh SDK agent session context documentation to describe the expanded provenance outcome statuses and resolver attempt semantics.

Tests:

  • Add unit and integration coverage for durable merge receipts across clone boundaries and for version-skewed merge fence behavior.
  • Extend provenance health and storage health tests to cover invalid legacy value classification, warnings, and projection through health vectors.
  • Update SDK runtime and init/merge safety tests to reflect the new provenance outcomes, fenced attributes markers, and environment isolation.

Chores:

  • Update public SDK surface, changelog entries, and PM agent history/issue records to capture the new context-integrity and provenance behavior.

Summary by cubic

Makes context integrity durable across clones and safe across client versions. Adds a privacy-safe merge-receipts store, versions the managed merge fence, tightens provenance outcomes, and improves health diagnostics.

  • New Features

    • Persist merge-decision receipts as hash-only sidecars in the tracker; keep raw values clone-local; expose unified listing and a value_availability flag.
    • Version the managed .gitattributes merge-driver fence (pm-cli:merge-drivers:v2) so older pm releases don’t rewrite it; auto-migrate and repair on install.
    • Add a not_configured provenance outcome; health/validate scan bounded history and publish aggregate invalid-value classes (boolean/single-digit) without leaking values.

  • Bug Fixes

    • Treat only same-harness inputs as resolver attempts; ignore foreign AI_AGENT signals and sandbox bleed-through in tests.
    • Make merge receipts visible in fresh clones and CI via durable summaries; block version-skewed commands from rewriting the merge fence.

Fixes #921, #922, #948