From 44e9f81d507a2324ee0e348d765ea1b9a03e7f6f Mon Sep 17 00:00:00 2001 From: max Date: Sun, 4 Jan 2026 10:37:16 -0800 Subject: [PATCH] docs: document asymmetric error handling in initTownAgentBeads (gt-m39yd) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain why agent bead creation failures are hard errors while role bead creation failures are soft errors (log and continue). Agent beads are identity beads that form the CV/reputation ledger foundation. Role beads are documentation templates not required for agent operation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- internal/cmd/install.go | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/internal/cmd/install.go b/internal/cmd/install.go index 1f7a3923..0724611c 100644 --- a/internal/cmd/install.go +++ b/internal/cmd/install.go @@ -331,6 +331,16 @@ func ensureRepoFingerprint(beadsPath string) error { // // These beads are stored in town beads (~/gt/.beads/) and are shared across all rigs. // Rig-level agent beads (witness, refinery) are created by gt rig add in rig beads. +// +// ERROR HANDLING ASYMMETRY: +// Agent beads (Mayor, Deacon) use hard fail - installation aborts if creation fails. +// Role beads use soft fail - logs warning and continues if creation fails. +// +// Rationale: Agent beads are identity beads that track agent state, hooks, and +// form the foundation of the CV/reputation ledger. Without them, agents cannot +// be properly tracked or coordinated. Role beads are documentation templates +// that define role characteristics but are not required for agent operation - +// agents can function without their role bead existing. func initTownAgentBeads(townPath string) error { bd := beads.New(townPath)