PR #622 - unbraind/pm-cli

Summary

This wide SDK/CLI tranche turns the relationship graph into a durable, governable project-context platform:

persist fingerprint-keyed graph query results across CLI processes with atomic writes, bounded retention, invalidation, and pm graph index status/rebuild/clear operations
add governance audit baselines with signed drift, raw duplicate-row detection, per-type coverage profiles, isolate exemptions, and remediation planning
emit component-scoped ordering-cycle mutation advisories without re-running whole-workspace SCC analysis
preserve public SDK, CLI, MCP, completion, generated-contract, documentation, and agent-oriented compact-output parity

pm items

Verification

Greptile pre-push review 84ef563e-f412-44be-80e5-462936a5134d: 5/5, no actionable findings after two accepted fixes
318 test files / 5,993 tests; exact 100% statements, branches, functions, and lines
all linked tests for the three active items passed
ESLint, jscpd (zero clones), CodeFactor rules, 100% docstrings, package-boundary, token-budget, contracts, docs/skills, and secret gates passed
88-command package-first dogfood passed
fresh packed-package temp project proved cross-process cache hits, mutation invalidation, saved baseline drift, CLI index rebuild, and custom company/VCS relationship modeling through the public SDK
latest pm-changelog 2026.7.18 check reports no changelog drift
tracker validation/history/storage integrity passed; health retains only the known five actionable unknown-author history events outside this tranche

Remaining canonical scope

The three broad features remain open after this tranche for their explicitly recorded longer-horizon work (true delta maintenance, temporal/what-if variants, migration/backfill, and million-item evaluation). They will be released from in-progress after merged-head proof rather than falsely closed.

Summary by cubic

Adds a durable, cross-process graph index, baseline-aware governance audits with typed coverage deltas, and incremental mutation advisories to speed graph queries and strengthen integrity checks. Snapshot diffs now tolerate and migrate legacy baselines with normalized item types.

New Features
- Durable graph index persisted under runtime with atomic writes, fingerprint keys (including extension relationship semantics), and cross-process locking for read/merge/write and clear; expose status/rebuild/clear via pm graph index, --rebuild, --clear, and include durable hit/miss/off in results. Malformed result maps are rejected early and maintenance flags are scope-validated.
- Governance baselines: pm graph audit --save-baseline stores a signed census; audits show change-since-baseline deltas with signed per-type coverage changes; add per-type coverage profiles and --exempt-isolate-type; detect duplicate_dependency_row (and legacy variant) with remediation; decoding hardened (reject null/array-shaped type counts); duplicate-dependency ordering is deterministic and locale-independent. Legacy baselines are auto-migrated and type names normalized during diffing.
- Incremental mutation advisories: component-scoped ordering-cycle detection without full workspace SCC runs; works directly from normalized dependency rows. Remediation plan honors isolate-type exemptions.
- CLI/MCP/SDK parity: add index subcommand and new flags in contracts and completion; docs updated; new durable-cache module. Filters resolve via the shared extension-aware relationship registry.
Migration
- Warm or manage the index with pm graph index, pm graph index --rebuild, and pm graph index --clear. Persistence auto-enables above a size threshold; otherwise opt in with --rebuild.
- Establish an audit baseline once with pm graph audit --save-baseline; future audits will report deltas, including per-type coverage changes. Older baselines are migrated automatically during reads.
- Use --exempt-isolate-type <Type[,Type…]> to mark isolate types as policy-valid.
- First run will rebuild caches due to the updated graph fingerprint (now also includes extension relationship semantics).