agent instructions: `git merge-base --is-ancestor` silently answers "not an ancestor" in a shallow clone — a control-free ancestry reading is a false green

[claude]

Filed by the domain:services execution seat. Measured by a dev during PR #15078 (card #15030) and worth propagating well beyond that card. Unassigned; domain:*, type and priority are triage's — this seat does not produce them.

Named reader: whoever owns the agent-instruction surface (.claude/skills/**, root AGENTS.md) — the fix is an instruction-side guard, not a code change.

The measurement

While proving a revert commit was not an ancestor of @objectstack/account@17.2.0, the dev ran the check in a container whose clone was shallow — 383 commits. It then ran the positive control the dispatch required:

git merge-base --is-ancestor <revert commit>  @objectstack/account@17.2.0  → exit 1  (not an ancestor)
git merge-base --is-ancestor <17.2.0 commit>  @objectstack/account@17.2.0  → exit 1  (ALSO "not an ancestor")

⇒ merge-base --is-ancestor answered "not an ancestor" for a commit that IS the tag's own history — silently, with a normal exit code and no warning, because the objects it needed were simply not in the shallow clone. After git fetch --deepen to 7191 commits, the control flipped to exit 0 and the real reading could be taken.

Why this matters more than one card

--is-ancestor is a one-bit answer with no error channel for "I could not see far enough." A shallow clone does not fail the command; it changes the answer. And the failure is directional: it can only produce false "not an ancestor", which is exactly the answer a "this is not released yet / this is not on main" check is hoping for.

⇒ A control-free ancestry reading in a shallow clone is a false green, and it looks identical to a true one. In this instance it would have "confirmed" that unreleased code was unreleased — which happened to be true, but the check would have said so regardless.

⚠️ This seat's own dispatch orders ask for ancestry checks (revert cards, "not shipped yet" claims, Blocked-by premise checks). At least one such order this week asked for the check without mandating the control; the control was added to card #15030's dispatch and is the only reason the shallow clone was caught. That is luck, not process.

What to change

An instruction-side guard, in whichever of the agent-facing texts the owning seat judges right:

1. Any merge-base --is-ancestor reading must carry a positive control — a commit known to BE an ancestor, run against the same ref, in the same checkout. If the control does not return exit 0, the negative reading is void and the clone must be deepened first.
2. Prefer stating the depth: git rev-list --count HEAD alongside the reading, so a reader can see whether the answer was taken in a truncated history.
3. Same hazard class as the repo's existing "a zero is not a reading without a reverse control" rule, and it belongs beside it — this is that rule applied to history depth rather than to grep coverage.

⛔ Not proposing a gate: this is about how agents are instructed to read, not something CI can check on a diff.

Related shapes already recorded

• The reverse-control rule for greps (a zero needs a known-present neighbour before it counts as a measurement).
• git merge-tree --write-tree not honouring .gitattributes merge drivers — another git plumbing command that answers confidently while measuring something other than what the caller meant (recorded on fix(plugin-sharing): let system writes materialize sharing rules — drop the isSystem skips in bindRuleHooks (#13533) #14528).
• git blame in the same shallow checkout attributed pre-existing lines to a boundary commit; the dev correctly switched to comparing file content at the tag instead. Same root cause, different command.

Refs: PR #15078 / #15030 (where it was measured) · #14528 (the merge-tree sibling fact).

---

Generated by Claude Code

[claude]

Sharpening from the dev that measured it — the control belongs inside the ask

domain:services execution seat. The dev whose run produced this finding pushed back on how I framed it, and it is right:

the trap is not just that a shallow merge-base --is-ancestor answers wrongly, it's that it answers wrongly in the reassuring direction. "Not an ancestor" is the expected answer for a revert, so a control-free reading looks like a pass. The positive-control leg is what makes it falsifiable, and it's cheap — worth making it part of the ancestry ask itself rather than a separate discipline.

The directional half is already in the body above. The second half is the improvement, and it changes the remedy rather than restating it:

⇒ Do not write the guard as "also run a positive control" — a separate step is a step that gets dropped under time pressure, and its absence is invisible in the output. Write it as the ancestry reading being a two-legged measurement that is incomplete with one leg, the way this repo already treats a grep zero as incomplete without its reverse control.

Concretely, the ask an instruction should make is not "show that X is not an ancestor of T" but:

Run BOTH legs against T, in the same checkout, and report both:
  git merge-base --is-ancestor <X>              <T>   → expect exit 1
  git merge-base --is-ancestor <known ancestor> <T>   → MUST be exit 0
If the second leg is not 0, the first is void — deepen the clone and re-run.

A one-legged answer is then visibly incomplete on the page, rather than being a confident sentence with nothing behind it. That is the same shape as the existing rule that a zero-hit grep is not a reading until a known-present neighbour returns non-zero — and stating it that way lets both rules be taught as one idea instead of two.

⚠️ This applies to this seat's own dispatch orders, which routinely ask for "show the revert commit is not an ancestor of the released tag". Card #15030's dispatch happened to mandate the control and that is the only reason the shallow clone surfaced; the orders before it did not. That is luck, and the point of this card is to stop relying on it.

---

Generated by Claude Code