Phase 153: Hash labeling & disambiguation across all interfaces

[jsilvanus]

Summary

This PR schedules Phase 153 to fix hash ambiguity across gitsema's user-facing outputs (CLI, MCP, HTTP, HTML).

Problem: Users see unlabeled hashes like [abc1234] in search results and naturally interpret them as commit hashes (the Git-level identifier they know). In reality, these are blob hashes (content-addressed, internal implementation detail). This causes confusion, especially when LLMs/Claude read the output.

Example:

0.898  src/auth/login.ts  [abc1234]

Users think [abc1234] is a commit hash. It's actually a blob hash.

Solution

Root cause: src/core/search/ranking.ts:53 defines renderResults(), which outputs unlabeled hashes. This function ripples across:

• CLI: gitsema search, first-seen, code-search
• MCP: semantic_search, code_search, search_history
• HTTP: /search, /first-seen (text rendering mode)
• HTML: Search results, evolution visualization

Fix: Add blob: prefix to distinguish hash types. Single-line change that cascades across all interfaces.

Impact

What changes (user-facing)

• CLI: [abc1234] → [blob:abc1234]
• MCP text output: Same prefix added
• HTML: Column header "Hash" → "Blob Hash", cells show blob: prefix
• OpenAPI docs: Clarify blobHash vs firstCommit fields
• MCP interpretations: Guide LLMs on hash types

What doesn't change (backward compatible)

• JSON field names: blobHash, firstCommit unchanged
• Database schema: No changes
• Structured JSON responses: Field names unchanged
• API response structure: No breaking changes

Risk Assessment

Low risk:

• Text-only enhancement (not parsed by clients)
• Single-line core change cascades automatically
• No schema/API/structure changes
• All existing tests should pass

Files in this PR

1. docs/hash-labeling-plan.md (new)

   • Complete design document with problem analysis
   • Solution overview across 5 scopes
   • Implementation order and acceptance criteria
   • Testing strategy and risk assessment

2. docs/PLAN.md (modified)

   • Added Phase 153 entry after Phase 152
   • Linked to design doc
   • Defined 6-item scope
   • Listed acceptance criteria

Next Steps (When Ready to Implement)

Use /execute-plan Phase 153 to:

1. Update src/core/search/ranking.ts:60 (1-line change)
2. Add tests to tests/ranking.test.ts
3. Update HTML renderers
4. Update OpenAPI docs
5. Update MCP interpretations
6. Verify all interfaces
7. Add changeset
8. Mark phase complete

Related Issues

Closes #hash-surfacing (internal audit finding)

---

📋 Checklist for implementation phase:

• Update renderResults() function
• Add hash-labeling unit tests
• Update HTML renderers for visual consistency
• Update OpenAPI field descriptions
• Update MCP tool interpretations
• Verify CLI output across commands
• Verify MCP text output
• Verify HTTP text rendering
• Verify HTML visualization
• Add changeset
• Mark phase complete in PLAN.md

🤖 Generated with Claude Code

---

Generated by Claude Code

[jsilvanus]

@copilot Please see the plan for phase 153 in this PR (see diff) and complete the phase 153.

[Copilot]

@copilot Please see the plan for phase 153 in this PR (see diff) and complete the phase 153.

Phase 153 is now complete. Here's what was implemented:

Core change (src/core/search/ranking.ts): renderResults() now outputs [blob:abc1234] instead of [abc1234]. This single-line change cascades automatically to CLI (search, first-seen, code-search), MCP text output (semantic_search, search_history, code_search), and HTTP text rendering (/search, /first-seen?rendered=true).

HTML renderers (htmlRenderer-search.ts, htmlRenderer-evolution.ts): "Hash" column headers → "Blob Hash"; cells show blob: prefix. The file-evolution renderer now shows commit:abc1234 for commit hashes, making the type explicit in both directions.

OpenAPI (openapi.ts): blobHash field description updated from 'Git blob SHA-1' to 'Git blob OID (content-addressed hash, 40 hex chars). Identifies blob content uniquely — not a commit hash.'

MCP interpretations (interpretations.ts): semantic_search, search_history, and first_seen entries updated with guidance that [blob:…] marks a content-addressed blob hash, not a commit hash.

Tests (tests/ranking.test.ts): existing hash test updated to assert [blob:a3f9c2d]; 4 new hash-labeling tests added covering renderResults, renderFirstSeenResults, and renderResultsByLevel.

No JSON field names, API shapes, or database schema were changed — fully backward compatible.

[jsilvanus]

@copilot Please resolve conflicts and update PR desc.

[Copilot]

@copilot Please resolve conflicts and update PR desc.

Resolved the merge conflict by bringing this branch up to date with origin/main, kept the Phase 153 hash-labeling work intact, regenerated the synced skill docs, and pushed the result as commit 308254b.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.