Declare the pm CLI floor in the field the CLI actually enforces - #43

Reviewer's Guide

Aligns the pm CLI compatibility floor across manifest and package metadata, pins the development CLI version, and adds tests to ensure the three declarations stay consistent, along with the corresponding changelog and pm agent history updates.

Sequence diagram for pm CLI enforcement of pm_min_version during extension install and health

sequenceDiagram
  actor User
  participant pm_cli
  participant extension_manifest

  User->>pm_cli: pm extension install
  pm_cli->>extension_manifest: load manifest.json
  alt [pm_min_version > pm_cli_version]
    pm_cli-->>User: ok: false (install refused)
    User->>pm_cli: pm --help
    pm_cli-->>User: extension command absent
    User->>pm_cli: pm health
    pm_cli-->>User: ok: false, extension_pm_min_version_unmet
  else [pm_min_version <= pm_cli_version]
    pm_cli-->>User: ok: true (install succeeds)
    User->>pm_cli: pm --help
    pm_cli-->>User: extension command listed
    User->>pm_cli: pm health
    pm_cli-->>User: ok: true
  end

File-Level Changes

Summary by CodeRabbit

• Bug Fixes

  • Updated the minimum supported PM version to 2026.8.3.
  • Pinned the development CLI to 2026.8.15 for consistent compatibility.
  • Unsupported PM versions are now rejected directly.

• Tests

  • Added regression checks for compatibility declarations, version ordering, and unsupported-version handling.

• Documentation

  • Added an Unreleased changelog entry describing the compatibility-floor correction.
  • Improved merge handling for managed extension files.

Walkthrough

The change aligns PM compatibility declarations, adds regression tests for version consistency, records the resolved issue, updates the changelog, and revises PM merge-driver attributes for extension files.

Changes

Compatibility floor alignment

PM merge attributes

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: 🔵 Low · up to 08ba0

The change correctly aligns the enforced CLI compatibility floor and adds regression coverage, but the PM audit records still contain inaccurate post-close event details. Append-only corrections should be added before merging; this is a bounded metadata risk with no expected runtime impact.

Possibly related issues

• Extension manifest can declare a version bound in a field nothing reads, and no tool warns pm-cli#1032 — Addresses the same PM compatibility-floor and manifest consistency behavior.

Possibly related PRs

• unbraind/pm-github#19 — Modifies the PM CLI compatibility declarations in package.json and manifest.json.
• unbraind/pm-github#23 — Updates PM CLI dependency versions in package.json.
• unbraind/pm-github#29 — Modifies the PM CLI dependency and PM-related .gitattributes rules.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

@greptileai review
/gemini review
@coderabbitai full review

Reviewer context for this change:

1. The claim being made is narrow. The manifest floor is set to the version the peerDependencies floor already declares. No new compatibility claim is introduced — the point is that the two enforcement paths (npm at install time, the pm CLI at extension load) read different fields, and only the npm-facing one was populated correctly.
2. .gitattributes is expected in this diff. It is the merge-driver fence being rewritten to the :v2: form by the newer pinned CLI through the prepare script, not a hand edit.
3. Please check specifically: whether the version comparison in the new test is correct for this fleet's YYYY.M.D scheme — note 2026.8.7 vs 2026.8.15, where a lexicographic compare gets the wrong answer, which is why it compares numeric components — and whether any other consumer in this repo reads a compatibility floor from a third place that this change does not bind.
4. A finding I would consider valid: any path by which the manifest floor and the peer floor can diverge without failing the test, or any reachable state where the pinned dev CLI could be below the declared floor.
5. Not useful here: suggesting the peerDependencies range be made an exact pin. It is deliberately a >= floor so any newer host CLI satisfies it; the exact pin belongs in devDependencies only. Both conventions are asserted by the test.

#!/bin/bash
set -euo pipefail

echo '--- changed files ---'
git diff --name-status HEAD^ HEAD

echo '--- diff ---'
git diff --no-ext-diff --unified=80 HEAD^ HEAD -- \
  .gitattributes manifest.json package.json package-lock.json \
  test/compatibility-floor.test.ts

echo '--- targeted file outlines ---'
for file in manifest.json package.json test/compatibility-floor.test.ts; do
  if [ -f "$file" ]; then
    echo "### $file"
    case "$file" in
      *.ts) ast-grep outline "$file" --items all || true ;;
      *) cat -n "$file" ;;
    esac
  fi
done

echo '--- compatibility metadata consumers ---'
rg -n -i -C 4 \
  '(pm_min_version|peerDependencies|devDependencies|`@unbrained/pm-cli`|`@unbrained/pm-cli`|compatibility.{0,30}(floor|version)|minimum.{0,30}(version|pm))' \
  -g '!package-lock.json' -g '!node_modules/**' .

echo '--- package scripts and pm configuration references ---'
rg -n -C 3 '"(prepare|test|typecheck|postinstall)"|pm\s+(test|health)|pm-cli' \
  package.json README.md .github .agents test 2>/dev/null || true

#!/bin/bash
set -euo pipefail

echo '--- changed files ---'
git diff --name-status HEAD^ HEAD

echo '--- compact diff for changed files ---'
git diff --no-ext-diff --unified=20 HEAD^ HEAD -- \
  .gitattributes manifest.json package.json package-lock.json \
  test/compatibility-floor.test.ts CHANGELOG.md

echo '--- current manifest and package declarations ---'
for file in manifest.json package.json test/compatibility-floor.test.ts; do
  echo "### $file"
  cat -n "$file"
done

echo '--- operational references to compatibility declarations ---'
rg -n -i -C 5 \
  '(pm_min_version|`@unbrained/pm-cli`|peerDependencies|devDependencies)' \
  -g '!package-lock.json' \
  -g '!CHANGELOG.md' \
  -g '!**/.agents/**' \
  -g '!dist/**' \
  -g '*.{ts,tsx,js,mjs,cjs,json,yml,yaml,md}' \
  .

echo '--- manifest loading and package-json loading sites ---'
rg -n -C 5 \
  '(readFileSync|readFile|import\s+.*manifest\.json|require\s*\(.{0,80}manifest\.json|package\.json)' \
  -g '!package-lock.json' \
  -g '!**/.agents/**' \
  -g '!dist/**' \
  -g '*.{ts,tsx,js,mjs,cjs}' \
  .

echo '--- test inventory and test runner configuration ---'
find test -maxdepth 2 -type f -print | sort
jq '{scripts, peerDependencies, devDependencies, engines}' package.json

@unbraind Full review completed. I found no actionable issues.

The regression test compares numeric version components. It correctly orders 2026.8.15 above 2026.8.7.

The test prevents these invalid states:

• The peer floor is not a plain >=YYYY.M.D range.
• manifest.json pm_min_version differs from the peer floor.
• The development CLI is not an exact pin.
• The pinned development CLI is below the manifest floor.

I found no third operational compatibility-floor declaration or consumer. The only other version requirement is an index.ts error message for the commitItemMutations SDK feature at >=2026.7.20. That requirement is below the enforced 2026.8.3 floor.

The .gitattributes v2 fence and extension rules are consistent with the pinned CLI update.

Greptile Summary

The PR aligns the host-enforced manifest floor with the existing peer dependency floor and pins the development CLI for reproducible tooling.

• Sets manifest.json’s pm_min_version to 2026.8.3.
• Pins @unbrained/pm-cli to 2026.8.15 and updates the resolved lockfile graph.
• Adds regression coverage binding the peer floor, manifest floor, and development pin.
• Updates generated merge-driver attributes, changelog history, and PM issue artifacts.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Peer[package.json peer floor >=2026.8.3] --> Npm[npm compatibility enforcement]
  Manifest[manifest.json pm_min_version 2026.8.3] --> Host[pm CLI activation enforcement]
  Dev[Exact development pin 2026.8.15] --> Tests[Compatibility-floor regression tests]
  Peer --> Tests
  Manifest --> Tests
  Tests --> Aligned[Consistent compatibility floor]

_{Reviews (11): Last reviewed commit: "Narrow the untrusted manifest field inst..." | Re-trigger Greptile}

@coderabbitai full review
@greptileai review
/gemini review

New commit pushed. This round adopted every finding from the last one, and one of them exposed a gap in my own evidence that is worth stating plainly.

CodeRabbit noticed the close reason claimed more than the recorded mutations showed. The claim was "all three assertions proved to fail on revert". Only two were: the assertion that peerDependencies must be a >= floor rather than an exact pin had never been mutated at all. A passing assertion that has never been observed failing is not evidence yet — and that is precisely the defect class this PR exists to close, so it could not stand.

Complete mutation table now, run per repository against the exact tree:

Also in this round: the version comparison now rejects a non-three-part floor before comparing (previously NaN propagated and the assertion blamed version ordering for a malformed value); the missing-field diagnostic no longer overstates the gap, since npm does still enforce peerDependencies for a locally resolved dependency; and the closed item carries resolution, expected_result and actual_result plus an appended note recording that its title changed twice and its close reason once after closure, with the reason for each.

What I would most like challenged: any assertion in compatibility-floor.test.ts that still has no mutation which fails it, and any way the manifest floor and the peer floor could diverge without the test noticing. Those are the two things this change actually promises.

Not useful here: suggesting the peerDependencies range become an exact pin (it is deliberately a floor, and the test asserts that), or editing CHANGELOG.md directly (it is generated from the pm item title; a direct edit fails changelog:check).

#!/bin/bash
set -euo pipefail

echo '--- current PR diff ---'
git diff --no-ext-diff --unified=80 HEAD^ HEAD -- \
  manifest.json package.json package-lock.json .gitattributes CHANGELOG.md \
  test/compatibility-floor.test.ts \
  .agents/pm/issues/pm-github-7d1h.toon \
  .agents/pm/history/pm-github-7d1h.jsonl

echo '--- test structure ---'
ast-grep outline test/compatibility-floor.test.ts --items all
echo '--- complete compatibility test ---'
cat -n test/compatibility-floor.test.ts

echo '--- compatibility declarations ---'
for file in manifest.json package.json; do
  echo "### $file"
  cat -n "$file"
done

echo '--- compatibility declaration consumers and assertions ---'
rg -n -i -C 5 \
  '(pm_min_version|`@unbrained/pm-cli`|compatibility-floor|peerDependencies|devDependencies|parseVersion|parse.*version|assert\.(equal|match|ok|deepEqual))' \
  -g '!package-lock.json' -g '!node_modules/**' -g '!dist/**' .

echo '--- PM item and append-only history ---'
for file in .agents/pm/issues/pm-github-7d1h.toon .agents/pm/history/pm-github-7d1h.jsonl; do
  if [ -f "$file" ]; then
    echo "### $file"
    cat -n "$file"
  fi
done

@unbraind Full review complete. I found no actionable issues.

test/compatibility-floor.test.ts prevents a divergence between the peer floor and manifest.json:

• The peer declaration must be a plain three-part >= floor.
• manifest.json must contain a string pm_min_version.
• The manifest floor must equal the peer floor after removal of >=.
• The development CLI must be an exact three-part pin.
• The numeric component comparison rejects a pin below the manifest floor. It correctly orders 2026.8.15 above 2026.8.7.

The mutation table covers each compatibility property. It also covers the manifest version-format guard. I found no third operational compatibility-floor declaration or consumer. The index.ts SDK feature requirement remains lower than this floor.

I also checked the PM-item correction record. It preserves the original close reason and appends the correction in the history stream. This follows the repository’s append-only audit rule.

Learnt from: unbraind
Repo: unbraind/pm-github PR: 19
File: CHANGELOG.md:3-3
Timestamp: 2026-07-28T04:22:06.541Z
Learning: In pm-github and its related packages, PM item history is append-only and audited. If a close reason contains an inaccurate historical verification claim, preserve it and add a correction note that records the original claim, why it was untrue, and the verified current state; do not silently rewrite historical records.

@coderabbitai review
@greptileai review
/gemini review

Please review the latest head. Two commits landed since the last review here, both driven by findings on sibling PRs in this same wave — every package carrying this change gets the same fixes, so a finding raised on one repo is applied to all eleven:

1. The version comparison had a branch the suite could never reach. The pin and the floor are the same version in this package, so atOrAbove short-circuits on equality and its ordering branch was never executed by any assertion — and V8 does not report a branch it never reaches, so a coverage gate would not have flagged it either. It is now driven directly over synthetic pairs, including the trap where 2026.8.7 must NOT satisfy a floor of 2026.8.15.
2. The correction note misdescribed this item’s own history. It claimed the title changed twice after closure and that close_reason was corrected. Derived from the actual stream instead: the field corrected was resolution, close_reason still holds the text recorded at closure, and on three of the eleven packages one of those updates landed before the close. Each item now states its own close timestamp and its own pre/post-close counts.

What I would most like challenged: any assertion in compatibility-floor.test.ts that still has no mutation which fails it.

#!/bin/bash
set -euo pipefail

echo '--- PR commits and changed files ---'
git log --oneline -6
git diff --name-status HEAD~2..HEAD

echo '--- latest two-commit diff: review targets ---'
git diff --no-ext-diff --unified=50 HEAD~2..HEAD -- \
  test/compatibility-floor.test.ts \
  manifest.json package.json \
  .agents/pm/issues/pm-github-7d1h.toon \
  .agents/pm/history/pm-github-7d1h.jsonl

echo '--- test outline ---'
ast-grep outline test/compatibility-floor.test.ts --items all

echo '--- test source ---'
cat -n test/compatibility-floor.test.ts

echo '--- compatibility declarations ---'
for file in manifest.json package.json; do
  echo "### $file"
  cat -n "$file"
done

echo '--- mutation and verification evidence ---'
rg -n -i -C 8 \
  '(mutation|baseline|restored|peer range|exact pin|pm_min_version|compatibility-floor|atOrAbove|2026\.8\.(7|15))' \
  .agents test CHANGELOG.md README.md 2>/dev/null || true

echo '--- metadata consumers outside lockfiles and PM records ---'
rg -n -i -C 4 \
  '(pm_min_version|`@unbrained/pm-cli`|peerDependencies|compatibility.{0,30}(floor|version)|minimum.{0,30}(version|pm))' \
  -g '!package-lock.json' -g '!node_modules/**' -g '!dist/**' -g '!**/.agents/**' \
  .

echo '--- corrected PM item and event history ---'
for file in .agents/pm/issues/pm-github-7d1h.toon .agents/pm/history/pm-github-7d1h.jsonl; do
  if [ -f "$file" ]; then
    echo "### $file"
    cat -n "$file"
  fi
done

#!/bin/bash
set -euo pipefail

echo '--- complete compatibility test ---'
cat -n test/compatibility-floor.test.ts

echo '--- exact latest two-commit diff ---'
git diff --no-ext-diff --unified=30 HEAD~2..HEAD -- \
  test/compatibility-floor.test.ts \
  .agents/pm/issues/pm-github-7d1h.toon \
  .agents/pm/history/pm-github-7d1h.jsonl

echo '--- per-commit target diff ---'
for commit in HEAD~1 HEAD; do
  echo "### $commit"
  git show --no-ext-diff --format=fuller --unified=25 "$commit" -- \
    test/compatibility-floor.test.ts \
    .agents/pm/issues/pm-github-7d1h.toon \
    .agents/pm/history/pm-github-7d1h.jsonl
done

echo '--- focused mutation evidence ---'
rg -n -i -C 4 \
  '(compatibility-floor\.test|atOrAbove|lexicographic trap|lower-bound mutation|revert-proof|mutation)' \
  .agents/pm/issues/pm-github-7d1h.toon \
  .agents/pm/history/pm-github-7d1h.jsonl \
  README.md CHANGELOG.md .github 2>/dev/null || true

echo '--- test scripts and mutation tooling ---'
jq '{scripts,devDependencies}' package.json
fd -HI -t f -E node_modules -E dist | rg '(^|/)(mutation|mutant|test|check|verify)'

@unbraind Full review complete. I found no actionable issues.

test/compatibility-floor.test.ts now directly exercises the equality case and the day, month, and year ordering cases in both directions. The test rejects the 2026.8.7 versus 2026.8.15 lexicographic trap.

The recorded mutations cover the compatibility properties:

• Peer range changed from a >= floor to an exact pin.
• Manifest floor removed or changed.
• Manifest floor changed to a malformed two-part version.
• Development pin changed to a caret range.
• Development pin changed below the manifest floor.
• Numeric comparison changed to a string comparison or an unconditional success result.

The current declarations remain aligned:

• peerDependencies["@unbrained/pm-cli"]: >=2026.8.3
• manifest.json pm_min_version: 2026.8.3
• devDependencies["@unbrained/pm-cli"]: 2026.8.15

The item correction also matches its history. close_reason remains unchanged. The later correction changes resolution.

Learnt from: unbraind
Repo: unbraind/pm-github PR: 24
File: test/handler-failures.test.ts:151-176
Timestamp: 2026-07-29T21:36:14.496Z
Learning: When reviewing this fleet’s tests, ensure each test name is fully supported by explicit assertions. In particular, a test named for a specific error/exit-code mapping must assert that mapping (for example, `CommandError.exitCode === EXIT_CODE.NOT_FOUND`), not only a related error message; otherwise narrow the test name.

@sourcery-ai thank you — one adopted, one already landed, and the reasoning on both is worth recording.

Adopted: stop coercing the untrusted manifest field. String(extensionManifest.pm_min_version) turned every wrong shape into a plausible string before the pattern check saw it — an absent field became "undefined", a number became its decimal form — so the failure message complained about version format for what was really a type problem. The field is narrowed explicitly now, and the message names the actual type. Verified by setting pm_min_version to the number 20260803:

manifest.json pm_min_version must be a string to be comparable, got number

Declined, with reason: the declared type stays unknown, not string | undefined. manifest.json is untrusted JSON read off disk. Declaring the field a string would assert the exact property this file exists to verify, and TypeScript would then let a number flow through to a string comparison with no diagnostic at all. unknown forces the narrowing to be written, which is what makes the wrong shape produce an actionable message. I have added a comment saying so, so the next reader does not re-tighten it.

Already landed: the helper. Your second point — extract the inline numeric comparison — was done in the commit after the one you reviewed (c5d0217f; head is now further along). It is atOrAbove(pinned, floor), and extracting it turned out to matter more than tidiness: the pin and the floor are the same version in this repository, so the ordering branch was never executed by any assertion, and pulling it into a named function is what made it testable over synthetic pairs. It now pins the trap that a semver-style comparator would also need care with — these are YYYY.M.D versions, so 2026.8.7 must not satisfy a floor of 2026.8.15, which a lexicographic or naive-semver compare gets wrong.

That last point is the reason I did not reach for an off-the-shelf comparator: 2026.8.15 is not a semver patch release, and treating it as one is how the bug this PR fixes gets reintroduced.

Additional evidence for this change, from a mistake I made elsewhere in the fleet.

While working on pm-rl I hit the failure mode this PR's exact pin prevents, and it is worth recording here because it is a concrete argument for the change rather than a theoretical one.

pm-rl pins ^2026.8.7; my shell had 2026.8.15 globally. Same working tree, two binaries:

Mirror images. There was no drift at all; I diagnosed with the wrong binary, repaired a phantom, and took CI red on a tree that had been green. That PR is closed and the defect is filed upstream as unbraind/pm-cli#1040.

This PR is what stops that happening here. A caret range lets a working copy and CI resolve different CLIs, and the drift verdict is version-dependent, so the two can disagree about whether the tracker is corrupt. An exact pin makes them the same binary.

Verified on this branch under its own pinned CLI — the one ci.yml invokes, not the one on my PATH:

./node_modules/.bin/pm --version   → 2026.8.15
./node_modules/.bin/pm health      → ok: true, 0 drift warnings

All twelve branches carrying this change report the same. That check is the one I should have run on pm-rl, and it is the one this pin makes trustworthy.