skills_install.py --report Reads Stale After a Correct merge-and-release, Because It Compares Commit Identity Rather Than Skill Content

[ptr727]

Found immediately after running merge-and-release end to end on #1397, by re-checking the machine
state the skill had just declared current.

Failure scenario, reproduced on this host

1. merge-and-release step 7 checks out main, fast-forwards it to the promoted tip, installs,
   and instructs: "confirm --report now reads current". It did, stale: false at f8e7491d.
2. Step 7 is followed by step 8, which is mandatory ("Run cleanup regardless of how steps 5
   through 7 ended") and fast-forwards the base clone back to develop.
3. --report now reads stale: true, on a machine whose install is correct and current:

"stamp": { "source": { "commit": "f8e7491d..." } },
"currentCommit": "aaaae368...",
"stale": true

So step 8 falsifies step 7's own confirmation, every time, by design rather than by accident.

Why the report is wrong here, not merely surprising

stale is a plain inequality between the stamp's commit and the checkout's HEAD. It is a
statement about commit identity, presented as a statement about whether this machine's
skills are current. On this host those two disagree completely:

• aaaae368 (the develop tip) is an ancestor of f8e7491d (the main tip), verified with
  git merge-base --is-ancestor. The installed commit is strictly newer.
• git diff aaaae368 f8e7491d -- .agents/skills/ .claude-plugin/ is empty. The skill content
  is byte-identical on both branches.

The machine has the newest skill content that exists, installed from the newest commit that exists,
and the report calls it stale.

Consequence

fleet-conformance-check exists to answer "is this machine current" and reads this report to do
it. Its answer here is a false stale, and the remedy it prescribes makes things worse rather than
better: reinstalling from develop stamps aaaae368, an older commit than the one already
installed, to silence a warning about content that never differed. The stamp moves backwards and
the report goes green, which is the exact inversion of what the stamp is for.

Every session working on develop after any promotion sees this, so it is the normal state rather
than an edge case.

Proposed dispositions, needing a decision rather than a fix

1. Compare content, not commit identity. The stamp could carry a digest of the two installed
   trees. .claude-plugin/fleet-skills/.source-digests/ already computes per-skill digests, so the
   input exists.
2. Compare reachability. Read as current when the stamped commit is a descendant of, or equal
   to, HEAD. Cheaper, and it would answer this case correctly, but it says nothing about a
   checkout that has moved sideways onto an unrelated branch.
3. Leave the engine alone and fix the two skills that read it. merge-and-release step 7 would
   stop instructing a confirmation that step 8 is about to invalidate, and
   fleet-conformance-check would stop treating a bare stale: true as actionable.

Option 1 is the one that makes the report mean what its field name says. Options 2 and 3 keep a
report that is only correct when read with a caveat that is nowhere written down.

[ptr727]

Maintainer decision, 2026-09-06: disposition 1, compare content rather than commit identity.

The stamp carries a digest of the installed trees, so stale becomes a statement about whether
this machine's skill content is current, which is what the field name says. The per-skill digests
under .claude-plugin/fleet-skills/.source-digests/ are the input, so the data already exists.

Dispositions 2 and 3 are declined. Reachability answers this case and stays silent on a checkout
moved sideways onto an unrelated branch, and leaving the engine alone keeps a report that is only
correct when read with a caveat written down nowhere.

Not yet implemented. This comment records the decision so the next session implements rather than
re-deciding it.

[ptr727]

Reproduced live on 2026-09-07, immediately after a correct merge-and-release of #1426, which is the exact circumstance this issue names.

stamp.source.commit  1d521521bcc077b8224ce00f73a38fca6a1eabcb   (main, release 2.0.583)
currentCommit        f86b149f2521232e982d3fd3c725b8fae6d2b242   (develop)
stale                true

The install is current in content. git diff origin/main origin/develop -- .agents/skills/ .claude-plugin/ is empty, so the two tips carry byte-identical skills trees, main differing only by the promotion merge commit sitting on top of develop.

What makes this reproducible rather than incidental: merge-and-release step 7 installs from a checkout on main, and step 8 then returns the base clone to develop. So the stamp always names a main commit and the next --report always reads a develop one, on every single promotion. The report is wrong at the end of every correct release, not occasionally.

Two operational consequences worth recording, since disposition 1 is decided but unimplemented:

• The check that merge-and-release step 7 prescribes, "confirm --report now reads current", passes only while the checkout is still on main. Run it before step 8, not after.
• A fleet-conformance-check run from an ordinary session, whose checkout is normally on develop, reads stale on a machine that is in fact current, which is the false positive that skill exists to rule out rather than produce.

No change requested here beyond what disposition 1 already settles. Filed as evidence and as a date.