PR #783 - unbraind/pm-cli

Summary

This broad SDK and CLI bundle strengthens project management = context management across merge safety, history integrity, extension authoring, agent-token efficiency, and fresh-clone governance.

generalizes the generated PM JSON merge fence to every nested tracker JSON document
conservatively reconciles independent additive JSON array changes while preserving conflict semantics for removals and edits
recognizes portable, package-owned merge drivers without trusting lookalike executables
invalidates history drift and derived item-metadata caches across append, rewrite, rollback, and bulk repair boundaries
makes bulk repair source-authoritative so stale indexes cannot manufacture integrity failures
shrinks lean structured output to decision-relevant data while retaining actionable pagination
preserves legacy output override compatibility and exports ServiceOverrideDecision for SDK authors
distinguishes required tracker structure from optional empty type folders in fresh-clone health
documents the contracts and regenerates the package-owned changelog with pm-changelog 2026.7.27

Why

Parallel agents need PM state to merge semantically across branches and clones, integrity checks must reflect the current source of truth immediately after mutation, and SDK extension authors need explicit typed ownership contracts. Agent-facing reads also need to spend context on project decisions instead of derivable request echoes.

PM lineage

Verification

pnpm lint
pnpm typecheck
pnpm contracts:check
docs/skills, context-evaluation, secret, dependency, and package-boundary gates
pnpm changelog:pm:check
pm health --check-only --skip-vectors --brief with zero warnings
pm validate --check-history-drift with zero drift
full sandboxed coverage: 380 files and 6,436 tests, exactly 100% statements/branches/functions/lines
fresh unrelated packed consumer: package-owned CLI resolution, npm/npx/bunx execution, lifecycle commands, lean output, health, validation, merge installation, and a real two-branch managed-extension merge

Dependency and security disposition

pnpm audit reports zero vulnerabilities
GitHub vulnerability and security alert inventories were empty at orientation
@sentry/node 10.68.0 was evaluated and rejected because its transitive declaration graph fails the mandatory packed TypeScript consumer boundary; 10.67.0 remains the latest compatible version
Node-floor-incompatible npm-package-arg 14 and the TypeScript 7 ecosystem transition remain linked to their canonical PM deferrals

Summary by Sourcery

Strengthen merge safety, history-drift cache invalidation, SDK service override contracts, and lean CLI JSON output, while generalizing JSON merge fences and updating health semantics and documentation.

Bug Fixes:

Ensure derived history drift caches are invalidated after history appends, rewrites, rollbacks, and bulk repairs.
Treat empty item-type directories as optional and warn only under strict directory health checks.
Accept portable, package-owned merge driver commands without trusting arbitrary executables, and continue flagging malformed or stale definitions.
Preserve output service-override compatibility by formalizing decisions, treating legacy payload echoes as safe declines with deprecation warnings, and exporting the decision type for SDK authors.
Compact lean JSON output to omit CLI request echoes and inactive pagination metadata while keeping actionable cursors.
Extend JSON merge fences and drivers to cover all nested authoritative JSON documents and conservatively compose additive JSON arrays without masking edit/removal conflicts.

Enhancements:

Add SDK-level tests for context-integrity primitives across merge behavior, health checks, output formatting, and merge driver configuration.
Document new SDK contracts for lean envelopes, service overrides, history/cache coherence, and fresh-clone directory semantics, and update merge safety documentation to cover generalized JSON fences and portable drivers.

Documentation:

Update SDK and merge safety documentation to describe lean JSON envelopes, service override decisions, mutation-aware drift-cache invalidation, fresh-clone directory semantics, and generalized JSON merge fences.

Tests:

Introduce comprehensive unit tests for SDK and CLI context integrity, including JSON merge semantics, managed-extension merges, lean output projection, history drift cache invalidation, directory health, and portable merge drivers.

Chores:

Regenerate PM agents, issues, histories, and changelog entries to track the new merge, cache, output, and dependency evaluation work.
Record evaluation of Sentry 10.68.0 compatibility and retain 10.67.0 as the supported version.

Summary by cubic

Hardens SDK/CLI merge safety, history integrity, and agent-friendly output. Adds full JSON fence coverage, portable merge drivers, lean reads, mutation-aware cache invalidation, clearer fresh-clone health, and stricter reconcile previews.

New Features
- Generalized PM JSON merge fence to .agents/pm/**/*.json; .managed-extensions.json now uses pm-json.
- Recognizes portable, package-owned merge drivers and installs stable commands; health audits identity without trusting paths.
- Adds conservative three-way reconciliation for additive JSON arrays; preserves multiplicity and keeps conflicts for edits/removals.
- Lean JSON reads omit filters, projection, sorting, now; include next_cursor only when paginating.
- Exports ServiceOverrideDecision; treats legacy output_format payload echo as a safe decline with a deprecation warning.
- Invalidates history drift cache on append/rewrite/rollback and bulk repair; runs before optional index work, surfaces non-missing cache failures, and forces source scans during bulk repair to avoid stale indexes.
- Merge-reconcile dry-run now fails closed on drift, pending receipts, or non-green validation.
- Fresh-clone health distinguishes required tracker structure from optional empty type folders and guards against custom-folder collisions.
Dependencies
- Evaluated @sentry/node 10.68.0 and retained 10.67.0 due to packed TypeScript consumer boundary failure.
- pnpm audit reports zero vulnerabilities.