sergio/takana

Documenta los tags anotados de diffutils/findutils-xargs/kustomize y por qué rompían las dos puntas
del mirror, y corrige la pregunta abierta: ningún servidor ha negado aún el fetch por sha suelto.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016v9ozVm44p6DB7EMXeZK4o

diff --git a/docs/adr/0013-mirror-de-fuentes.md b/docs/adr/0013-mirror-de-fuentes.md
index 1a421956..a7ab1e7a 100644
--- a/docs/adr/0013-mirror-de-fuentes.md
+++ b/docs/adr/0013-mirror-de-fuentes.md
@@ -205,12 +205,36 @@ eso el silencio se paga con comentarios explícitos en el código.
   hoy eso lo dispara una persona corriendo `mirror-git-poblar.sh`, no el latido.
 - Qué hacer con los repos cuyo servidor **no permite fetch por SHA suelto**
   (`uploadpack.allowReachableSHA1InWant` desactivado): ahí el `--depth 1` del commit exacto falla y
-  hay que caer a un clon completo.
+  hay que caer a un clon completo. **Todavía no ha aparecido ninguno.**
 
   El poblador reporta el **stderr real de git**, no una conjetura. Lo escribí al revés la primera
   vez — imprimía siempre `✗ upstream no da el commit` — y en la primera tanda marcó así a tres
-  recetas (`diffutils`, `findutils-xargs`, `kustomize`) cuyos commits **sí se traen a mano**. Un
-  fallo en ese punto puede ser el servidor negando el sha, pero también un timeout, DNS o un
-  rate-limit de GitHub, y cada uno se arregla distinto. **Un diagnóstico hardcodeado convierte un
-  fallo transitorio en una conclusión falsa sobre upstream**, que es exactamente el error que ya
-  costó caro en la ruta relativa del bundle.
+  recetas (`diffutils`, `findutils-xargs`, `kustomize`) cuyos commits **sí se traen a mano**. En
+  cuanto imprimió el error de verdad, la causa resultó ser otra por completo: el pin de esas tres no
+  es un commit (§ siguiente). Un fallo ahí puede ser el servidor negando el sha, pero también un
+  timeout, DNS, un rate-limit o —como fue— un bug propio, y cada uno se arregla distinto. **Un
+  diagnóstico hardcodeado convierte cualquier fallo en una conclusión falsa sobre upstream**, que es
+  el mismo error que ya costó caro con la ruta relativa del bundle.
+
+## El pin de una receta no siempre es un commit
+
+`diffutils`, `findutils-xargs` y `kustomize` pinean en su campo `commit` el SHA de un **objeto tag
+anotado** (`v0.5.0`, `0.9.1`, `kustomize/v5.8.1`), no de un commit. Es legítimo: `git archive` acepta
+un tag igual que un commit, y para `hash_inputs` un SHA es un SHA — `git:{commit}` no distingue el
+tipo de objeto y no tiene por qué. Pero rompía las dos puntas del mirror, y en las dos por la misma
+suposición sin escribir:
+
+- **El poblador** hacía `update-ref refs/heads/hammer <sha>`, y una rama sólo apunta a commits:
+  *«trying to write non-commit object»*. Ahora pela con `<sha>^{commit}` para la rama y, si hubo que
+  pelar, manda el objeto tag aparte en `refs/tags/hammer-objeto`. Sin ese segundo ref el bundle
+  desempaqueta bien pero el `cat-file -e <commit>` del otro lado no encuentra lo que la receta pide:
+  un mirror **correcto pero inútil justo para esas recetas**.
+- **hammer** escribía el `commit` de la receta en el fichero `shallow`, que sólo admite SHAs de
+  commit. Ya no lo supone: lee la frontera del propio bundle con `git bundle list-heads`, que imprime
+  la lista de refs **sin necesitar los objetos** y por eso sirve justo antes del fetch. Y trae
+  `refs/*:refs/*` en vez de un ref concreto, para que el objeto tag viaje con lo demás.
+
+Los bundles del formato viejo (un solo ref, los 339 ya subidos) siguen sirviendo sin tocarlos: para
+ellos `list-heads` devuelve el commit y el refspec ancho encuentra ese mismo ref único. Comprobado
+con una receta de cada forma contra un `repo` que no resuelve por DNS, para que el mirror sea la
+única fuente posible.