PR #990 - unbraind/pm-cli

Summary

add a public grammar-aware recovery primitive so global option values never become help command names
reject ambiguous files/docs add-and-remove batches before item or history mutation and expose the primitive through the packed SDK
migrate 45 inline ENOENT catches to explicit optional-absence or exact-missing contracts and ratchet the raw catch census to zero
make Windows retry/path assertions platform-native and keep assertion output visible in coverage shard logs
make local coverage report independent test and exact-threshold verdicts, with a real all-package install budget

PM lineage

Verification

486 test files and 7,251 tests pass
exact coverage is 100/100/100/100 with zero uncovered counts
lint, duplicate detection, contracts, public SDK surface, 100 percent docstrings, package boundaries, token/context gates, graph and record assurances pass
tracked-secret scan passes and pnpm audit reports no known vulnerabilities
fresh temporary tracker accepted both global-flag placements, atomic no-write refusal, valid follow-up mutations, packed SDK import, npx, and bunx
pm-changelog 2026.8.12 check reports CHANGELOG.md current

Closes #984
Closes #989

Summary by Sourcery

Enforce context-safe recovery and atomic linked-artifact mutations across the SDK and CLI, while tightening filesystem absence contracts and improving coverage gating behavior.

New Features:

Expose a grammar-aware recovery command resolver in the SDK so agents and CLI consistently infer the subcommand without leaking global option values.
Introduce a public linked-artifact mutation guard that rejects ambiguous add/remove/migrate batches before any item or history changes are applied.

Enhancements:

Refine test runner coverage mode to run coverage thresholds independently of test execution and return distinct exit codes and messages for test, coverage, and combined failures.
Standardize optional-file handling by centralizing ENOENT/ENOTDIR and missing-entry detection into shared helpers and applying them across locks, checkpoints, history, governance, telemetry, merge fences, and other subsystems.
Document new recovery and linked-artifact mutation contracts in the SDK guide, including guarantees about non-ambiguous transactions and help example resolution.
Adjust CI coverage-shard configuration to use a default reporter for more visible assertion output in shard logs.

Tests:

Add unit tests covering ambiguous files/docs add-and-remove/migrate batches, SDK mutation guard behavior, recovery command resolution across global flags, absence-tolerance gate CLI flags, and new test runner coverage verdict semantics.
Extend existing tests to reflect platform-sensitive recovery suggestions and updated filesystem absence helpers.

Summary by cubic

Makes SDK and CLI mutations safer and error guidance accurate: grammar-aware command recovery, atomic linked-artifact mutations, unified file-absence handling, and portable, exact coverage reporting.

New Features
- Grammar-aware recovery command resolution so global flags never become command names; guided errors now show correct examples. (pm-lph0y6, closes #984)
- Atomic linked-artifact mutations: mixed add/remove for the same path is rejected with linked_artifact_mutation_conflict. SDK export: assertLinkedArtifactMutationIsUnambiguous. (pm-c6urop, closes #989)
Bug Fixes
- Unified optional/missing file semantics with isFileAbsentError and isFileMissingError; removed 45 ENOENT-only catches and added a zero-tolerance gate. (pm-6xlyss)
- Windows CI reliability: platform-native errno/path assertions and visible shard assertion output. (pm-j668gl)
- Coverage is portable and independent of test success; exact-threshold verdicts and a real all-package install budget; CI adds default reporter for shard logs. (pm-h9gsix)