drift-analyzer 2.2.0__tar.gz → 2.3.1__tar.gz

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/_partials/konventionen.md

@@ -60,6 +60,31 @@ Keine Prompt-spezifischen Bewertungssysteme einführen.
 Bei GitHub-Issue-Erstellung den Template-Block aus `_partials/issue-filing.md` verwenden.
 Keine individuellen Issue-Templates pro Prompt.
 
+## Versions-Freshness
+
+Jeder Prompt MUSS sicherstellen, dass die aktuellste `drift-analyzer`-Version verwendet wird.
+Ein Test gegen eine veraltete Version hat keinen Erkenntniswert.
+
+**Field-Test-Prompts** (externe Repos — PyPI-Release):
+
+```bash
+pip install --upgrade drift-analyzer   # Immer zuerst upgraden
+drift --version                        # Installierte Version dokumentieren
+pip index versions drift-analyzer 2>/dev/null | head -1  # Optional: Verfügbare Versionen prüfen
+```
+
+Falls `pip install --upgrade` scheitert (Netzwerk, Index), MUSS dies im Report dokumentiert
+und die aktuell installierte Version explizit angegeben werden.
+
+**Interne Prompts** (Drift-Workspace — Dev-Version):
+
+```bash
+pip install -e .                       # Dev-Version aus dem Workspace installieren
+drift --version                        # Muss mit pyproject.toml übereinstimmen
+```
+
+Beide Szenarien: Die genutzte drift-Version MUSS im Report-Header oder Repo-Profil erscheinen.
+
 ## Querverweise
 
 Jeder Prompt SOLLTE am Ende seines Frontmatter-Bereichs oder in einem dedizierten Abschnitt

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/drift-agent-ux.prompt.md

@@ -73,9 +73,12 @@ Erstelle Artefakte unter `work_artifacts/agent_ux_<YYYY-MM-DD>/`:
 
 Erkunde die CLI als Zero-Knowledge-Agent.
 
+**Dev-Version sicherstellen** (siehe `_partials/konventionen.md` → Versions-Freshness):
+
 ```bash
+pip install -e .   # Dev-Version aus Workspace
 drift --help
-drift --version
+drift --version    # Muss mit pyproject.toml übereinstimmen
 ```
 
 Für jedes Top-Level-Kommando:

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/drift-agent-workflow-test.prompt.md

@@ -82,8 +82,11 @@ New-Item -ItemType Directory -Path $sandbox -Force
 
 ### Phase 1: Installation & Discovery
 
+**Dev-Version sicherstellen** (siehe `_partials/konventionen.md` → Versions-Freshness):
+
 ```bash
-drift --version
+pip install -e .   # Dev-Version aus Workspace
+drift --version    # Muss mit pyproject.toml übereinstimmen
 drift --help
 ```
 

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/drift-ai-integration.prompt.md

@@ -74,6 +74,13 @@ Erstelle Artefakte unter `work_artifacts/ai_integration_<YYYY-MM-DD>/`:
 
 ### Phase 0: AI-facing Oberflächen inventarisieren
 
+**Dev-Version sicherstellen** (siehe `_partials/konventionen.md` → Versions-Freshness):
+
+```bash
+pip install -e .   # Dev-Version aus Workspace
+drift --version    # Muss mit pyproject.toml übereinstimmen
+```
+
 Identifiziere alle derzeit exponierten AI-facing Features:
 - `copilot-context`
 - `export-context` (Formate: `instructions`, `prompt`, `raw`)

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/drift-ci-gate.prompt.md

@@ -70,6 +70,13 @@ Erstelle Artefakte unter `work_artifacts/ci_gate_<YYYY-MM-DD>/`:
 
 ### Phase 0: Gate-relevante Kommandos inventarisieren
 
+**Dev-Version sicherstellen** (siehe `_partials/konventionen.md` → Versions-Freshness):
+
+```bash
+pip install -e .   # Dev-Version aus Workspace
+drift --version    # Muss mit pyproject.toml übereinstimmen
+```
+
 Identifiziere die für CI relevanten Kommandos und Optionen, insbesondere:
 - `check` (mit `--fail-on`, `--json`, `--compact`, `--output-format`)
 - `validate`

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/drift-onboarding.prompt.md

@@ -69,6 +69,13 @@ Erstelle Artefakte unter `work_artifacts/onboarding_<YYYY-MM-DD>/`:
 
 ### Phase 0: Neueinsteiger-Perspektive einnehmen
 
+**Dev-Version sicherstellen** (siehe `_partials/konventionen.md` → Versions-Freshness):
+
+```bash
+pip install -e .   # Dev-Version aus Workspace
+drift --version    # Muss mit pyproject.toml übereinstimmen
+```
+
 Nimm an, du hast kein repo-spezifisches Drift-Wissen außer dem, was CLI und generierte Dateien liefern.
 
 Dokumentiere:

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/drift-signal-quality.prompt.md

@@ -78,6 +78,13 @@ Erstelle Artefakte unter `work_artifacts/signal_quality_<YYYY-MM-DD>/`:
 
 ### Phase 0: Signal-Inventar erstellen
 
+**Dev-Version sicherstellen** (siehe `_partials/konventionen.md` → Versions-Freshness):
+
+```bash
+pip install -e .   # Dev-Version aus Workspace
+drift --version    # Muss mit pyproject.toml übereinstimmen
+```
+
 Signale aus realer CLI-Ausgabe inventarisieren und Abkürzungen, Namen und verfügbare Beschreibungen erfassen.
 
 Mindestens prüfen:

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/field-tests/drift-context-eval.prompt.md

@@ -70,7 +70,17 @@ Erstelle Artefakte unter `work_artifacts/context_eval_<YYYY-MM-DD>/`:
 
 ### Phase 0: Repo-Profil erstellen
 
-Identisches Profil wie in `drift-finding-audit` Phase 0:
+**Versions-Freshness sicherstellen:**
+
+```bash
+pip install --upgrade drift-analyzer   # Aktuellste Version von PyPI
+drift --version                        # Version dokumentieren
+```
+
+Falls das Upgrade scheitert (Netzwerk, Index), dies im Report dokumentieren
+und mit der aktuell installierten Version fortfahren.
+
+**Identisches Profil wie in `drift-finding-audit` Phase 0:**
 
 | Eigenschaft | Wert |
 |-------------|------|
@@ -79,6 +89,7 @@ Identisches Profil wie in `drift-finding-audit` Phase 0:
 | Sprache(n) | [Python / TypeScript / Mixed] |
 | Framework(s) | [Django / Flask / FastAPI / Express / None / ...] |
 | Ungefähre Größe | [Dateien / LOC] |
+| drift-Version | [VERSION] |
 
 ### Phase 1: Alle Export-Formate ausführen
 

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/field-tests/drift-field-test.prompt.md

@@ -67,6 +67,18 @@ Erstelle Artefakte unter `work_artifacts/field_test_<YYYY-MM-DD>/`:
 
 ### Phase 0: Voraussetzungen prüfen
 
+**Versions-Freshness sicherstellen:**
+
+```bash
+pip install --upgrade drift-analyzer   # Aktuellste Version von PyPI
+drift --version                        # Version dokumentieren
+```
+
+Falls das Upgrade scheitert (Netzwerk, Index), dies im Report dokumentieren
+und mit der aktuell installierten Version fortfahren.
+
+**System-Voraussetzungen:**
+
 ```bash
 python --version          # ≥ 3.11 erforderlich
 git --version             # Git muss vorhanden sein

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.github/prompts/field-tests/drift-finding-audit.prompt.md

@@ -75,7 +75,17 @@ Erstelle Artefakte unter `work_artifacts/finding_audit_<YYYY-MM-DD>/`:
 
 ### Phase 0: Architektur-Profil erstellen
 
-Analysiere das Repository, um einen informierten Oracle aufzubauen:
+**Versions-Freshness sicherstellen:**
+
+```bash
+pip install --upgrade drift-analyzer   # Aktuellste Version von PyPI
+drift --version                        # Version dokumentieren
+```
+
+Falls das Upgrade scheitert (Netzwerk, Index), dies im Report dokumentieren
+und mit der aktuell installierten Version fortfahren.
+
+**Repository analysieren**, um einen informierten Oracle aufzubauen:
 
 ```bash
 # Struktur verstehen
@@ -98,6 +108,7 @@ ls -la  # oder: Get-ChildItem
 | Sprache(n) | [Python / TypeScript / Mixed] |
 | Framework(s) | [Django / Flask / FastAPI / Express / None / ...] |
 | Ungefähre Größe | [Dateien / LOC] |
+| drift-Version | [VERSION] |
 | Bekannte Architekturentscheidungen | [z.B. "Django-apps-Struktur", "Hexagonal", "Layered"] |
 
 ### Phase 1: Oracle aufbauen

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/.gitignore

@@ -27,6 +27,7 @@ htmlcov/
 Thumbs.db
 Desktop.ini
 site/
+audit_results/
 drift_score.json
 work_artifacts/
 master-backlog/

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 - Introduce configurable finding-context triage policy with precedence-based glob rules to keep non-operational findings out of default remediation queues unless explicitly requested.
 - Add `--progress json` option to `scan` and `analyze` commands for structured JSON-lines progress feedback on stderr, enabling agents to distinguish running from hung processes (#104).
+- `drift check` now supports `--save-baseline` and `--max-findings` options for CI parity with `drift analyze` (#116).
+- `drift diff` JSON output now includes `score_basis` field (`"historical"` or `"zero_default"`) to clarify when `score_before` reflects actual repo baseline vs. synthetic zero (#119).
+- Add `csv` output format for `drift analyze` and `drift check` to export findings as one-row-per-finding tabular output (`signal,severity,score,title,file,start_line,end_line`) (#14).
+- Add a dedicated PFS signal reference page in docs with detection details, scoring formula, severity thresholds, remediation guidance, and example outputs (#24).
+- Add regression test suites for edge-case projects and framework-specific ISD fixtures to improve signal robustness across minimal and real-world repository shapes (#13, #26).
 
 ### Changed
 
@@ -11,6 +16,8 @@
 
 ### Fixed
 
+- Reduce DIA false positives by requiring structural context for plain markdown slash-tokens (e.g. `async/`, `scan/`, `connectors/`) before emitting missing-directory findings, while preserving explicit path references in code spans/backticks (#121).
+- Add trailing newlines in CSV formatter and CSV tests to satisfy lint gate requirements and keep pre-push checks green.
 - Surface file I/O errors in `analyze`, `check`, and `scan` commands as structured `DRIFT-2003` errors with exit code 2 instead of unhandled `OSError` tracebacks.
 - Validate `--max-findings` range (1–200) in `drift scan` via `click.IntRange` and reject out-of-range values with exit code 2.
 - Improve `DRIFT-2003` action message to explicitly suggest checking output path writability and parent directory existence.
@@ -26,11 +33,21 @@
 - Add `description` fields to all MCP tool parameters via `Annotated[type, Field(description=...)]` and include descriptions in `drift mcp --schema` catalog output so agents can infer valid parameter ranges and formats (#110).
 - Replace all non-ASCII characters (emoji severity icons, arrows, ellipsis) in Markdown export output with ASCII equivalents to eliminate mojibake on Windows (#111).
 - Add cross-reference notes between `copilot-context` and `export-context` outputs so agents using either surface are made aware of the complementary context (#112).
+- Suppress Rich progress bar on stderr for machine-readable output formats (`--json`, `--sarif`) to prevent PowerShell `NativeCommandError` from non-JSON prelude (#118).
+- Map git-root-relative paths to repo-relative paths in `analyze_diff` and `parse_git_history` so `--repo` on nested subdirectories no longer leaks parent-repo file scope (#117).
+- `drift self` error guidance now suggests valid next actions (`drift scan`/`drift analyze`) instead of invalid `--repo` flag (#120).
+
+## [2.3.0] - 2026-04-03
+
+Short version: Align release metadata with current project version.
+
+### Changed
+
+- Sync top changelog release marker to 2.2.0 so release-discipline checks match [project] version in pyproject.toml.
 
 ## [2.1.3] - 2026-04-02
 
 Short version: Keep release metadata aligned after CI runner hardening updates.
-
 ### Fixed
 
 - Align release bookkeeping so `pyproject.toml` and top changelog release stay in sync for pre-push release-discipline checks.

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drift-analyzer
-Version: 2.2.0
+Version: 2.3.1
 Summary: Deterministic architectural drift detection for AI-accelerated Python repositories through cross-file coherence analysis
 Project-URL: Homepage, https://sauremilk.github.io/drift/
 Project-URL: Repository, https://github.com/mick-gsk/drift

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/SECURITY.md

@@ -4,6 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 2.3.x   | :white_check_mark: |
+| 2.2.x   | :white_check_mark: |
 | 2.1.x   | :white_check_mark: |
 | 2.0.x   | :white_check_mark: |
 | 1.5.x   | :white_check_mark: |
@@ -17,7 +19,7 @@
 | 0.7.x   | :white_check_mark: |
 | < 0.7   | :x:                |
 
-Current release line: **v2.1.0**.
+Current release line: **v2.3.0**.
 
 ## Reporting a Vulnerability
 

drift_analyzer-2.3.1/decisions/ADR-011-csv-output-format.md

@@ -0,0 +1,52 @@
+---
+id: ADR-011
+status: proposed
+date: 2026-04-03
+supersedes:
+---
+
+# ADR-011: CSV-Ausgabeformat fuer Findings
+
+## Kontext
+
+Drift bietet derzeit rich-, json-, sarif-, agent-tasks- und github-Ausgaben.
+Fuer viele Teams fehlt ein leicht importierbares Tabellenformat fuer schnelle
+Weiterverarbeitung in Kalkulation, einfache Filter-Pipelines oder PM-Boards.
+
+## Entscheidung
+
+Wir fuehren ein neues Output-Format `csv` fuer `drift analyze` und `drift check`
+ein. Die Ausgabe enthaelt pro Finding genau eine Zeile mit stabilem Header:
+
+`signal,severity,score,title,file,start_line,end_line`
+
+Rahmenbedingungen:
+
+- Implementierung in `src/drift/output/csv_output.py`.
+- Nutzung des Python-Standardmoduls `csv` (keine neue Abhaengigkeit).
+- Deterministische Zeilenreihenfolge analog zu bestehenden
+  maschinenlesbaren Ausgaben.
+- Keine Aenderung an Signalberechnung, Scoring oder Severity-Logik.
+
+Explizit nicht Teil dieser ADR:
+
+- keine neuen Felder im CSV-Schema in dieser Iteration
+- keine Aenderung an `self`/`scan`-Format-Optionen
+
+## Begründung
+
+CSV verbessert Einfuehrbarkeit und Handlungsfaehigkeit bei minimaler
+Komplexitaet: einfacher Datenaustausch ohne Schema-Parser, reproduzierbar und
+ mit bestehender CLI-Ausgabe konsistent.
+
+## Konsequenzen
+
+- Additiver CLI-Output-Kanal ohne Breaking Change.
+- Zusätzlicher Pflegeaufwand fuer einen weiteren Serializer (niedrig).
+- CSV bleibt bewusst kompakt; tiefe Metadaten bleiben in JSON/SARIF.
+
+## Validierung
+
+- Unit-Tests fuer Header, Feldreihenfolge und CSV-Escaping.
+- CLI-Choice-Test fuer `--output-format csv`.
+- Policy §10 Lernzyklus-Status: unklar (Nutzerfeedback nach Feldnutzung).

drift_analyzer-2.3.1/docs-site/reference/signals/pfs.md

@@ -0,0 +1,184 @@
+# Pattern Fragmentation Signal (PFS)
+
+**Signal ID:** `PFS`  
+**Full name:** Pattern Fragmentation Score  
+**Type:** Scoring signal (contributes to drift score)  
+**Default weight:** `0.16`
+
+---
+
+## What PFS detects
+
+PFS identifies modules where the **same category of code pattern** (e.g. error handling, data validation, logging) is implemented in **multiple incompatible ways**. This fragmentation is a strong indicator of architectural drift — often caused by different AI generation sessions producing slightly different implementations of the same concept.
+
+### Before — fragmented error handling
+
+```python
+# services/payment_service.py
+def process_payment(amount):
+    try:
+        validate(amount)
+        return {"status": "ok"}
+    except ValueError as e:
+        raise PaymentError(str(e)) from e
+
+def refund_payment(transaction_id):
+    try:
+        result = lookup(transaction_id)
+        return True
+    except Exception as e:        # ← bare except, different style
+        print(e)
+        return False
+
+def cancel_payment(payment_id):
+    result = lookup(payment_id)
+    if result is None:             # ← no try/except at all
+        logger.warning("Not found")
+        return False
+    return True
+```
+
+Three functions, three different error handling approaches in the same module. PFS flags this as fragmentation.
+
+### After — consolidated pattern
+
+```python
+# services/payment_service.py
+class PaymentError(Exception):
+    pass
+
+def process_payment(amount):
+    try:
+        validate(amount)
+        return {"status": "ok"}
+    except ValueError as e:
+        raise PaymentError(str(e)) from e
+
+def refund_payment(transaction_id):
+    try:
+        result = lookup(transaction_id)
+        return True
+    except LookupError as e:
+        raise PaymentError(str(e)) from e
+
+def cancel_payment(payment_id):
+    try:
+        result = lookup(payment_id)
+        return True
+    except LookupError as e:
+        raise PaymentError(str(e)) from e
+```
+
+One consistent error handling pattern across the module.
+
+---
+
+## Why pattern fragmentation matters
+
+- **Maintenance cost multiplies** — each variant requires separate understanding and testing.
+- **Bugs hide in deviations** — the `except Exception: print(e)` variant silently swallows errors that the other variants would propagate.
+- **Onboarding friction** — new contributors cannot determine which pattern is the intended standard.
+- **AI generation amplifies fragmentation** — LLMs generate plausible but subtly different implementations each session, leading to variant accumulation over time.
+
+---
+
+## How the score is calculated
+
+$$
+\text{fragmentation\_score} = 1 - \frac{1}{\text{num\_variants}}
+$$
+
+| Variants | Score | Severity |
+|----------|-------|----------|
+| 2        | 0.50  | MEDIUM   |
+| 3        | 0.67  | MEDIUM   |
+| 4        | 0.75  | HIGH     |
+| 5+       | 0.80+ | HIGH     |
+
+**Spread boost:** When non-canonical instances spread across many files (> 2), a spread factor is applied:
+
+$$
+\text{spread\_factor} = \min\!\bigl(1.5,\; 1.0 + (\text{non\_canonical\_count} - 2) \times 0.04\bigr)
+$$
+
+The score is capped at 1.0.
+
+**Severity thresholds:**
+
+| Score range | Severity |
+|-------------|----------|
+| ≥ 0.7       | HIGH     |
+| ≥ 0.5       | MEDIUM   |
+| ≥ 0.3       | LOW      |
+| < 0.3       | INFO     |
+
+---
+
+## How to fix PFS findings
+
+1. **Identify the canonical variant** — PFS reports which variant is used most often (the "canonical" pattern). This is your consolidation target.
+2. **Migrate deviating instances** — Refactor non-canonical usages to match the dominant pattern. PFS lists affected files and line numbers.
+3. **Extract shared abstractions** — If variants serve genuinely different purposes, extract them into clearly named helpers or base classes.
+4. **Add linting rules** — Once consolidated, add project-specific lint rules or code review checklists to prevent re-fragmentation.
+
+---
+
+## Configuration
+
+In `drift.yaml` or `pyproject.toml`:
+
+```yaml
+# drift.yaml
+weights:
+  pattern_fragmentation: 0.16   # default weight (0.0 to 1.0)
+```
+
+```toml
+# pyproject.toml
+[tool.drift.weights]
+pattern_fragmentation = 0.16
+```
+
+Set to `0.0` to disable PFS scoring entirely. Increase the weight to prioritize fragmentation findings.
+
+---
+
+## Example output
+
+```json
+{
+  "signal_type": "pattern_fragmentation",
+  "severity": "high",
+  "score": 0.75,
+  "title": "error handling: 4 variants in services/",
+  "description": "4 error handling variants in services/ (6/10 use canonical pattern).\n  - payment_service.py:14 (refund_payment)\n  - payment_service.py:22 (cancel_payment)\n  - order_service.py:8 (create_order)",
+  "fix": "Consolidate to the dominant pattern (6×). 4 deviations in: payment_service.py, order_service.py.",
+  "metadata": {
+    "category": "error handling",
+    "num_variants": 4,
+    "canonical_count": 6,
+    "total_instances": 10
+  }
+}
+```
+
+---
+
+## Detection details
+
+PFS uses the following algorithm:
+
+1. **Collect patterns** from all parsed files (AST-extracted pattern instances with category and fingerprint).
+2. **Group by module** (parent directory) and pattern category.
+3. **Normalize fingerprints** — async/sync variants are treated as equivalent to reduce false positives.
+4. **Count unique variants** per module using fingerprint hashing.
+5. **Identify the canonical variant** (most-used) and report deviations.
+
+PFS is deterministic, AST-only, and does not require git history or LLM calls.
+
+---
+
+## Related signals
+
+- **MDS (Mutant Duplicates)** — detects near-identical functions. MDS finds copy-paste code; PFS finds the same *intent* implemented differently.
+- **COD (Code Duplication)** — detects exact or near-exact code blocks. COD finds duplication; PFS finds inconsistency.

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/mkdocs.yml

@@ -83,6 +83,8 @@ nav:
       - API and Outputs: reference/api-outputs.md
       - Negative Context: reference/negative-context.md
       - Performance: reference/performance.md
+      - Signals:
+          - PFS (Pattern Fragmentation): reference/signals/pfs.md
   - Product:
       - Product Strategy: product-strategy.md
       - Example Findings: product/example-findings.md

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "drift-analyzer"
-version = "2.2.0"
+version = "2.3.1"
 description = "Deterministic architectural drift detection for AI-accelerated Python repositories through cross-file coherence analysis"
 readme = "README.md"
 license = "MIT"

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/src/drift/analyzer.py

@@ -312,6 +312,18 @@ def analyze_diff(
         )
         return analysis
 
+    # Map git-root-relative paths to repo-relative paths when repo_path is
+    # a subdirectory of the git root (#117).
+    from drift.ingestion.git_history import _git_repo_prefix
+
+    prefix = _git_repo_prefix(repo_path)
+    if prefix:
+        mapped: list[str] = []
+        for fp in changed_files:
+            if fp.startswith(prefix):
+                mapped.append(fp[len(prefix):])
+        changed_files = mapped
+
     if not changed_files:
         return RepoAnalysis(
             repo_path=repo_path,

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/src/drift/api.py

@@ -9,6 +9,7 @@ contract.
 from __future__ import annotations
 
 import json
+from collections import Counter
 from collections.abc import Callable
 from pathlib import Path
 from types import SimpleNamespace
@@ -248,6 +249,28 @@ def _format_scan_response(
         )
         limited = ranked[:max_findings]
 
+    selected_signal_counts: Counter[str] = Counter(
+        signal_abbrev(f.signal_type) for f in selected_findings
+    )
+    included_signal_counts: Counter[str] = Counter(
+        signal_abbrev(f.signal_type) for f in limited
+    )
+    omitted_signals: list[dict[str, Any]] = []
+    for signal in sorted(selected_signal_counts.keys()):
+        total = selected_signal_counts[signal]
+        included = included_signal_counts.get(signal, 0)
+        omitted = max(total - included, 0)
+        if omitted:
+            omitted_signals.append({
+                "signal": signal,
+                "total": total,
+                "included": included,
+                "omitted": omitted,
+                "reason": "deprioritized_by_strategy",
+            })
+
+    omitted_signals.sort(key=lambda item: (-int(item["omitted"]), item["signal"]))
+
     prioritized_for_fix_first, excluded_for_fix_first, context_counts = split_findings_by_context(
         selected_findings,
         config,
@@ -308,6 +331,17 @@ def _format_scan_response(
         },
     )
 
+    if omitted_signals:
+        result["selection_diagnostics"] = {
+            "strategy": strategy,
+            "max_findings": max_findings,
+            "signals_with_omitted_findings": omitted_signals,
+            "note": (
+                "Some findings are not returned due to max_findings truncation "
+                "and selection strategy."
+            ),
+        }
+
     # detailed mode adds fix_first, recommended_next_actions, agent_instruction
     if detail == "detailed":
         result["fix_first"] = _fix_first_concise(
@@ -523,13 +557,21 @@ def diff(
 
         # Score comparison via trend context
         score_after = diff_analysis.drift_score
-        score_before = (
-            diff_analysis.trend.previous_score
-            if diff_analysis.trend and diff_analysis.trend.previous_score is not None
-            else 0.0
-        )
+        score_before: float = 0.0
+        if (
+            diff_analysis.trend is not None
+            and diff_analysis.trend.previous_score is not None
+        ):
+            score_before = diff_analysis.trend.previous_score
+            has_trend_baseline = True
+        else:
+            has_trend_baseline = False
         delta = round(score_after - score_before, 4)
 
+        # When no historical baseline exists, flag the score fields as
+        # synthetic so agents don't misinterpret zero as the repo baseline (#119).
+        score_basis = "historical" if has_trend_baseline else "zero_default"
+
         from drift.output.json_output import _priority_class
 
         drift_categories = sorted({_priority_class(f) for f in scoped_new}) if scoped_new else []
@@ -666,6 +708,7 @@ def diff(
             score_before=round(score_before, 4),
             score_after=round(score_after, 4),
             delta=delta,
+            score_basis=score_basis,
             score_regressed=delta > 0.0,
             confidence=confidence,
             diff_ref=diff_ref,

{drift_analyzer-2.2.0 → drift_analyzer-2.3.1}/src/drift/cli.py

@@ -86,11 +86,12 @@ def _build_error_payload(
     *,
     detail: str | None = None,
     hint: str | None = None,
+    suggested_action_override: str | None = None,
 ) -> dict[str, object]:
     """Build a v2.0 machine-readable error payload with recovery info."""
     info = ERROR_REGISTRY.get(error_code)
     recoverable = category == "user"
-    suggested_action = info.action if info else hint
+    suggested_action = suggested_action_override or (info.action if info else hint)
     return {
         "error": True,
         "schema_version": "2.0",
@@ -214,6 +215,7 @@ def safe_main() -> None:
                     exc.exit_code,
                     detail=exc.detail,
                     hint=exc.hint,
+                    suggested_action_override=exc.suggested_action,
                 ),
             )
         else: