Refuse incomplete pm corpora before GitHub sync

Merged
UN
2mo ago
+688-17

Summary

  • remove the arbitrary 10,000-row ceiling from pm-github's whole-workspace reader
  • request strict, full, unbounded pm output and validate every independent completeness, omission, pagination, budget, count, identity, and consumed-row contract
  • add adversarial decoder coverage plus a fresh-tracker installed-CLI acceptance containing both closed and open work
  • document fail-closed behavior and the 64 MiB transport guard
  • pin the development CLI/SDK toolchain to 2026.8.17

Why

Import idempotency, export, state sync, Projects v2 sync, and search fallback all rely on seeing every item. The previous reader accepted arrays and loosely shaped envelopes, defaulted missing rows to an empty array, ignored truthfulness receipts, and silently capped the corpus at 10,000 rows. A partial read could therefore recreate a closed imported issue or omit remote updates.

Project-management evidence

Verification

  • npm ci --ignore-scripts: 73 packages, 0 vulnerabilities
  • npm run release:check: pass (typecheck, build, 85/85 docstrings, behavioral coverage gate, production audit, package dry-run, changelog check)
  • focused compatibility + complete-corpus suite: 9/9
  • real fresh tracker: one closed GitHub-linked issue plus one open task returned intact
  • host latest CLI acceptance: 2026.8.17
  • bun install --no-save: pass
  • pm validate: storage/history integrity pass; pre-existing metadata/file warnings remain
  • pm health --strict-exit: pass with three pre-existing legacy provenance advisories
  • current tracked and all-object high-confidence credential scan: 0 findings

Independent remaining gates

This PR does not claim the separate exact-coverage mandate: current measured production coverage is 91.83% lines, 82.14% branches, and 91.75% functions, and operational scripts remain outside measurement. pm-github-9cjx owns that work.

The current tree contains no absolute host paths, but historical Git objects contain pre-existing path metadata and one machine-local commit identity. pm-github-zqad records the required forward gate and the maintainer decision needed before any destructive rewrite of already-published history/tags.

Summary by Sourcery

Enforce strict, complete whole-workspace pm reads before performing any GitHub import, export, or sync, failing closed on partial or unverifiable corpora.

Bug Fixes:

  • Ensure pm item reads use a strict, unbounded pm list-all contract and reject truncated, paginated, compacted, or otherwise incomplete outputs instead of treating them as partial workspaces.
  • Fix Windows invocation of the npm-installed pm CLI by enabling shell execution only on that platform while preserving direct execution elsewhere.

Enhancements:

  • Add comprehensive validation of pm list-all truthfulness envelopes, including completeness, omission, budget, counts, identities, and consumed fields, to guard idempotency and sync flows.
  • Document whole-workspace read safety guarantees and the PM_JSON_MAX_BUFFER transport cap in the README.
  • Introduce an installed-CLI acceptance test and adversarial decoder tests to verify complete open-and-closed corpus handling and robustness against malformed responses.

Build:

  • Pin the development pm CLI/SDK toolchain to @unbrained/pm-cli 2026.8.17.

Documentation:

  • Document the strict, fail-closed whole-workspace read behavior and guidance for raising the JSON buffer cap for large trackers.

Tests:

  • Add a complete-corpus test suite covering argv construction, cross-platform spawn options, strict decoder contracts, and real installed-CLI behavior on a fresh tracker.

Chores:

  • Record pm-github project-management history and tasks for completeness and coverage mandates in new .agents/pm files.

Summary by cubic

Refuses incomplete pm item corpora before any GitHub import, export, or sync, and hardens Windows execution to preserve argument boundaries. Previously we accepted loose arrays/envelopes and capped reads at 10,000 rows; now we require a strict, full, unbounded pm list-all contract and fail closed on any unverifiable output.

  • Validates pagination, completeness, omission, projection, budget, counts vs totals, unique identities, and consumed fields, then decodes rows; incomplete or contradictory receipts throw. Retains the 64 MiB transport guard.
  • Windows: relaunches the CLI via process.execPath using host PM_CLI_PACKAGE_ROOT to locate @unbrained/pm-cli’s declared bin.pm, verifies it resides inside the host package root, and never uses a shell; acceptance covers metacharacter paths and packed installs.
  • Adds completePmListArgs and decodeCompletePmItems and routes readPmItems through them; documents behavior in README; pins the development toolchain to @unbrained/pm-cli 2026.8.17; expands adversarial/installed-CLI tests.

Required actions

  • Ensure the host pm CLI is >= 2026.8.3.
  • For very large trackers, set PM_JSON_MAX_BUFFER to a larger value.
  • On Windows, ensure the host sets PM_CLI_PACKAGE_ROOT for the installed @unbrained/pm-cli; reads will fail if it is missing.