PR #961 - unbraind/pm-cli

Summary

make dependency mutations fail fast across SDK, CLI, bulk, and MCP paths while preserving explicit forward-reference and external-reference intent
make acceptance-criteria repairs atomic and lossless, with replacement/removal conflict contracts and deterministic receipts
keep legacy type coercion inside structured JSON output and harden workspace snapshot restore lease renewal
refresh generated SDK/CLI contracts, tests, agent documentation, and pinned GitHub Actions in one review tranche

PM lineage

Verification

full test suite: 468 files, 7141 tests passed
coverage: 100% statements, branches, functions, and lines
lint/static quality: ESLint, zero jscpd clones, 100% docstrings, package boundaries, SDK surface, token/context/tracker gates
security/docs: secret scan and docs-skills gate passed
manual clean-directory acceptance: dependency validation and opt-in, external targets, atomic criteria repair, JSON success/failure envelopes, snapshot preview and restore
grouped Actions update: PR #958 exact head had all CI, coverage, security, docs, and analysis checks green before incorporation

Review notes

The generated public-surface acknowledgement is intentional: the typed SDK now exposes explicit unresolved-dependency control and richer structured error details. Existing implicit dangling local edges now fail closed unless callers opt in.

Summary by Sourcery

Enforce lossless, fail-fast mutation contracts for acceptance criteria and dependencies across SDK, CLI, bulk, and MCP flows, while tightening workspace snapshot lock renewal and refreshing public contracts, docs, and CI tooling.

New Features:

Add explicit allowUnresolvedDeps options and validation that resolves local dependency targets up front, returning structured dependency_target_unresolved warnings when opt-in unresolved edges are intentional.
Expose richer structured mutation receipts, including acceptance_criteria_replaced warnings and type_coercion warnings, through SDK and CLI outputs.

Bug Fixes:

Prevent workspace snapshot restores from losing their writer lease by serializing and hardening lock heartbeat renewals.

Enhancements:

Make acceptance-criteria mutations atomic and lossless by rejecting unmatched removals with structured errors and disallowing conflicting replacement-plus-additive edits, including in bulk update-many flows.
Propagate dependency target validation and mutation option constraints consistently through update-many planning, dry-run behavior, and SDK/CLI tool schemas.
Retain legacy type synonym coercion strictly as structured JSON warning data instead of emitting stderr notes, improving agent-facing reliability.

CI:

Bump pinned pnpm and CodSpeed GitHub Actions and CodeQL actions to newer versions across CI, benchmarking, release, docs, and security workflows.

Documentation:

Update SDK, agent, and command documentation to describe lossless acceptance-criteria behavior, dependency target resolution requirements, and new unresolved-dependency controls.
Refresh PM lineage references to include lossless mutation contracts work items.

Tests:

Add comprehensive lossless mutation contract tests for acceptance criteria, dependency validation, type coercion, and bulk dry-run alignment, and update existing command, SDK, and integration tests to cover new options and behaviors.
Adjust test helpers and fixtures to default to allow-unresolved-deps where appropriate and to assert new warning tokens and error codes.

Summary by cubic

Makes SDK/CLI mutations lossless and predictable: unresolved local dependencies fail fast by default (opt-in allowed), acceptance-criteria edits are atomic, snapshot restore leases are safer, and outputs use clear, structured JSON. Also publishes structured mutation error codes with emitting-command mapping, enforces schema guardrails, updates docs/contracts/CHANGELOG, and pins GitHub Actions to newer SHAs.

New Features
- Dependency validation: reject unresolved local targets across SDK/CLI/MCP/bulk; opt in with --allow-unresolved-deps (or allowUnresolvedDeps). External refs with source_kind=external bypass lookup. Deterministic dependency ordering; structured unresolved_targets in error context.
- Acceptance criteria: unmatched removals fail with acceptance_criteria_remove_unmatched; list-level conflicts surface acceptance_criteria_mutation_conflict (mapped to update and update-many). CLI schema disallows mixing --acceptance-criteria with --add-ac/--remove-ac. Deterministic receipts.
- Structured output: type coercion and diagnostics stay inside JSON envelopes; PmCliErrorContext adds unmatched and unresolved_targets.
- Snapshot restore: deterministic lease renewal/refresh and cleanup to prevent orphaned work.
- Contracts/docs/changelog: regenerate error-code catalog (with emitting-command mapping) and aggregate contract fixture; update SDK/CLI docs and CHANGELOG. CI pins updated to latest SHAs for pnpm/action-setup, github/codeql-action/*, and CodSpeedHQ/action.
Migration
- Local dependency edges now fail closed unless you pass --allow-unresolved-deps (CLI) or set allowUnresolvedDeps (SDK). Prefer source_kind=external for cross-workspace targets.
- Do not mix --acceptance-criteria with --add-ac/--remove-ac on update/update-many. Use remove+add for one-entry repairs; unmatched removals error with structured guidance.
- JSON consumers should read structured fields (warnings and error context), including explicit dependency and acceptance-criteria receipts and new error codes.