From 29fda64866af9d34b6316d4d33b7b874d1175628 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive>
Date: Sun, 31 May 2026 16:23:45 +0200
Subject: [PATCH] docs/approvals.md: split sha vs tag scoping per argus on #833

---
 docs/approvals.md | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/approvals.md b/docs/approvals.md
index c9d988d2..ff4243ba 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -497,15 +497,18 @@ regular claude turn so the manager can react. Variants
   The recipient responds via `Answer { id, answer }` and the
   asker sees the matching `QuestionAnswered`.
 
-Optional `sha` / `tag` fields on `ApprovalResolved`, `Spawned`, and
-`Rebuilt` carry the canonical hive-c0re-vouched commit sha plus the
-applied-repo's terminal tag (`deployed/<id>` / `failed/<id>` /
-`denied/<id>` for approval-driven flows; `approved/<id>` for the
-rare bare-approval case where no underlying action runs). Both are
-`Option`: `None` on the paths that don't change the deployed commit
-(e.g. `auto_update::rebuild_agent` reapplying the existing main, or
-the dashboard `↻ R3BU1LD` button when the lock didn't move). When
-set, `git show <sha>` against `/agents/<n>/applied.git` inside the
+Optional `sha` field on `ApprovalResolved`, `Spawned`, and `Rebuilt`
+carries the canonical hive-c0re-vouched commit sha. Optional `tag`
+on `ApprovalResolved` and `Rebuilt` only — the spawn path always
+lands at `deployed/0`, so the tag is implicit and not echoed. The
+tag values for the variants that do carry it: `deployed/<id>` /
+`failed/<id>` / `denied/<id>` for approval-driven flows;
+`approved/<id>` for the rare bare-approval case where no underlying
+action runs. Both fields are `Option`: `None` on the rebuild paths
+that don't change the deployed commit (e.g.
+`auto_update::rebuild_agent` reapplying the existing main, or the
+dashboard `↻ R3BU1LD` button when the lock didn't move). When set,
+`git show <sha>` against `/agents/<n>/applied.git` inside the
 manager container yields the exact tree that was referenced.
 
 To add a new event: new `HelperEvent` variant + call sites + update