Document external_ref in content hash behavior (bd-9f4a)

- Added comprehensive code comments in collision.go explaining external_ref inclusion
- Documented content hash behavior in HASH_ID_DESIGN.md with examples
- Enhanced test documentation in collision_test.go
- Closes bd-9f4a, bd-df11, bd-537e

Amp-Thread-ID: https://ampcode.com/threads/T-47525168-d51c-4f56-b598-18402e5ea389
Co-authored-by: Amp <amp@ampcode.com>

internal/storage/sqlite/collision.go

@@ -144,6 +144,19 @@ func compareIssues(existing, incoming *types.Issue) []string {
 }
 
 // hashIssueContent creates a deterministic hash of issue content (excluding ID and timestamps)
+//
+// IMPORTANT: external_ref is included in the content hash. This means:
+//   - Adding/removing/changing external_ref changes the content hash
+//   - A local issue that gains an external_ref will have different content hash
+//   - This is intentional: external_ref is semantically meaningful content
+//
+// Implications:
+//   1. Rename detection won't match issues before/after adding external_ref
+//   2. Content-based collision detection treats external_ref changes as updates
+//   3. Idempotent import only when external_ref is identical
+//
+// This design choice ensures external system linkage is tracked as substantive content,
+// not just metadata. See docs/HASH_ID_DESIGN.md for more on content hash philosophy.
 func hashIssueContent(issue *types.Issue) string {
 	h := sha256.New()
 	_, _ = fmt.Fprintf(h, "title:%s\n", issue.Title)
@@ -155,6 +168,7 @@ func hashIssueContent(issue *types.Issue) string {
 	_, _ = fmt.Fprintf(h, "design:%s\n", issue.Design)
 	_, _ = fmt.Fprintf(h, "acceptance:%s\n", issue.AcceptanceCriteria)
 	_, _ = fmt.Fprintf(h, "notes:%s\n", issue.Notes)
+	// external_ref is included in content hash (see comment above)
 	if issue.ExternalRef != nil {
 		_, _ = fmt.Fprintf(h, "external_ref:%s\n", *issue.ExternalRef)
 	}

internal/storage/sqlite/collision_test.go

@@ -340,6 +340,17 @@ func TestHashIssueContent(t *testing.T) {
 	}
 }
 
+// TestHashIssueContentWithExternalRef verifies that external_ref is included in content hash.
+//
+// This test demonstrates the behavior documented in bd-9f4a:
+//   - Adding external_ref to an issue changes its content hash
+//   - Different external_ref values produce different content hashes
+//   - This is intentional: external_ref is semantically meaningful content
+//
+// Implications:
+//   - Rename detection won't match issues before/after adding external_ref
+//   - Collision detection treats external_ref changes as updates
+//   - Idempotent import only when external_ref is identical
 func TestHashIssueContentWithExternalRef(t *testing.T) {
 	ref1 := "JIRA-123"
 	ref2 := "JIRA-456"
@@ -365,11 +376,17 @@ func TestHashIssueContentWithExternalRef(t *testing.T) {
 	hash2 := hashIssueContent(issueWithRef2)
 	hash3 := hashIssueContent(issueNoRef)
 
+	// Different external_ref values should produce different hashes
 	if hash1 == hash2 {
 		t.Errorf("Expected different external refs to produce different hashes")
 	}
 
+	// Adding external_ref should change the content hash
 	if hash1 == hash3 {
 		t.Errorf("Expected issue with external ref to differ from issue without")
 	}
+
+	if hash2 == hash3 {
+		t.Errorf("Expected issue with external ref to differ from issue without")
+	}
 }