gossiphs: Instructions file for Codex

Development Habits and Architectural Principles

This document summarizes the core principles and development habits established during the evolution of gossiphs, specifically regarding its evaluation against compiler-based benchmarks like SCIP.

1. Metric Priorities

• Symbol Level: Focus exclusively on Precision. We care about whether the symbols gossiphs finds are "true" definitions/references. Recall is secondary as gossiphs is designed to be lightweight.
• File Level: Focus on both Precision and Recall. This is the primary dimension for architectural analysis. We aim to capture the "Main Road" of the project (Physical Dependencies) while providing "Bonus" insights (Logical Coupling).

2. Dependency Extraction Philosophy

• Explicit > Implicit: Prefer explicit code signals (e.g., import, use, require statements) over implicit heuristics (e.g., directory proximity).
• Physical Link Weighting: Links backed by explicit code imports should receive a massive score boost (e.g., 100.0) to ensure they appear at the top of the relation list.
• Logical Coupling: Git history serves as a supplement to find hidden dependencies that static analysis misses (e.g., config files linked to code).

3. Handling Symbol FQNs

• Base Name Matching: Since gossiphs often lacks full type resolution, use "Base Name" matching (matching the suffix of a symbol name) to bridge the gap between simple names and Fully Qualified Names (FQNs) used by indexers like SCIP.
• Collision Mitigation: To prevent "Simple Name Collisions" (e.g., New, init), enforce strict filters:
  • Non-qualified names require a physical link or high commit intersection (>= 3).
  • Qualified names require at least 1 common commit.
• Dynamic Specificity Filtering (IDF): Use Inverse Document Frequency to weight symbols. Rare symbols (high IDF) contribute more to the score than common ones (low IDF, e.g., init).
• Adaptive Collision Mitigation: Instead of hard counts, use Confidence = IDF * JaccardSimilarity. Links with low confidence are pruned unless backed by physical evidence.
• Entropy-based Pruning: For ambiguous symbols with many potential definitions, use Shannon entropy to penalize and prune low-signal links. This effectively "distributes credit" and suppresses noise in large projects.
• Score-Gap Pruning: When multiple definitions match a reference, only keep those within 80% of the top score. This prevents "ambiguous" links from polluting the graph.
• Temporal Decay: Prefer recent evidence over historical data. Commits are weighted using an exponential decay function based on their age (half-life default: 365 days).