drift-analyzer 2.6.2__tar.gz → 2.7.0__tar.gz

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/.github/copilot-instructions.md

@@ -193,6 +193,27 @@ python scripts/release_automation.py --full-release
 
 ---
 
+## MCP Fix-Loop — Optimierter Workflow für Finding-Behebung
+
+Wenn ein Agent Drift-Findings über MCP-Tools beheben soll, **muss** dieser Ablauf verwendet werden:
+
+1. **`drift_session_start(path=".", autopilot=true)`** — ein Aufruf statt vier (bündelt validate + brief + scan + fix_plan)
+2. **`drift_nudge(session_id=..., changed_files=...)`** — nach jeder Dateiänderung als schneller Inner-Loop (~0.2 s statt ~3 s für scan)
+3. **`drift_fix_plan(session_id=..., max_tasks=1)`** — nächsten Task holen (immer `max_tasks=1`)
+4. **`drift_diff(session_id=..., uncommitted=true)`** — nur einmal am Ende als Abschluss-Verifikation
+
+**Verboten im Fix-Loop:**
+- `drift_scan` nach jeder Dateiänderung (zu teuer, nutze `nudge`)
+- `session_start` ohne `autopilot=true` (verschenkt 4 Roundtrips)
+- `fix_plan` ohne `max_tasks=1` (unnötig große Responses)
+- Tool-Aufrufe ohne `session_id` (verliert Kontext)
+
+**Immer:** `agent_instruction` und `next_tool_call` aus Responses befolgen.
+
+Vollständiger Workflow: `.github/prompts/drift-fix-loop.prompt.md`
+
+---
+
 ## Schlussbestimmung
 
 Diese Policy ist verbindlich (Policy §18).

drift_analyzer-2.7.0/.github/prompts/drift-fix-loop.prompt.md

@@ -0,0 +1,144 @@
+---
+name: "Drift Fix-Loop"
+description: "Optimierter Agent-Workflow zum Beheben von Drift-Findings über MCP-Sessions. Nutzt session_start(autopilot=true) + nudge als Inner-Loop für minimale Roundtrips."
+---
+
+# Drift Fix-Loop
+
+Dieser Prompt beschreibt den optimalen Ablauf, um Drift-Findings in einem Workspace über MCP-Tools effizient zu beheben. Der Workflow minimiert Roundtrips und nutzt die vorhandene Session-Infrastruktur vollständig aus.
+
+> **Pflicht:** Vor Ausführung dieses Prompts das Drift Policy Gate durchlaufen
+> (siehe `.github/prompts/_partials/konventionen.md` und `.github/instructions/drift-policy.instructions.md`).
+
+## Relevante Referenzen
+
+- **Instruction:** `.github/instructions/drift-policy.instructions.md`
+- **Push Gates:** `.github/instructions/drift-push-gates.instructions.md`
+- **Skill:** `.github/skills/drift-effective-usage/SKILL.md`
+- **Skill:** `.github/skills/drift-commit-push/SKILL.md`
+- **MCP-Server:** `src/drift/mcp_server.py`
+- **Session-Management:** `src/drift/session.py`
+
+## Warum dieser Workflow
+
+Ein naiver Agent-Loop ruft pro Finding: `validate → scan → fix_plan → [edit] → scan → diff` auf.
+Jeder `scan`-Aufruf führt eine vollständige Repo-Analyse durch (~1–5 s). Bei mehreren Findings multipliziert sich die Wartezeit und die Roundtrips.
+
+**Dieser Workflow reduziert das auf:**
+1. Einen einzigen `session_start(autopilot=true)`-Aufruf (bündelt validate + brief + scan + fix_plan)
+2. `nudge` als schnellen Inner-Loop nach jeder Dateiänderung (~0.2 s statt ~3 s für scan)
+3. Einen einzigen `drift_diff` als Abschluss-Verifikation
+
+## Ablauf
+
+### Schritt 1 — Session starten mit Autopilot
+
+```
+drift_session_start(
+    path=".",
+    autopilot=true
+)
+```
+
+Dieser eine Aufruf führt automatisch `validate → brief → scan → fix_plan` aus und gibt die kombinierten Ergebnisse zurück. Die Session-ID wird in allen Folge-Aufrufen wiederverwendet.
+
+**Wichtig:** Die `session_id` aus der Antwort merken und an **jeden** weiteren Tool-Aufruf übergeben.
+
+### Schritt 2 — Ersten Task aus fix_plan bearbeiten
+
+Die Autopilot-Antwort enthält bereits den `fix_plan`. Den **ersten** Task nehmen und umsetzen.
+
+**Regel:** Immer nur einen Task gleichzeitig. Nicht mehrere Findings in einem Schritt mischen.
+
+### Schritt 3 — Nach jeder Dateiänderung: nudge
+
+```
+drift_nudge(
+    session_id="<session_id>",
+    changed_files="<pfad/zur/geänderten/datei.py>"
+)
+```
+
+`nudge` gibt schnelles Richtungsfeedback:
+- `direction`: improving / stable / degrading
+- `safe_to_commit`: true / false
+- `confidence`: pro Signal
+
+**Wenn `direction=degrading`:** Änderung rückgängig machen, anders lösen.
+**Wenn `safe_to_commit=true`:** Weiter mit nächstem Task oder Abschluss.
+
+### Schritt 4 — Nächsten Task holen (falls nötig)
+
+Wenn weitere Findings offen sind:
+
+```
+drift_fix_plan(
+    session_id="<session_id>",
+    max_tasks=1
+)
+```
+
+**Immer `max_tasks=1` verwenden.** Das reduziert die Response-Größe und den Parsing-Overhead erheblich.
+
+Dann zurück zu Schritt 2.
+
+### Schritt 5 — Abschluss-Verifikation
+
+Erst wenn alle Tasks bearbeitet sind:
+
+```
+drift_diff(
+    session_id="<session_id>",
+    uncommitted=true
+)
+```
+
+Prüfen:
+- `resolved_count` > 0
+- `new_count` == 0
+- Keine Regressionen
+
+## Zusammenfassung als Ablaufdiagramm
+
+```
+session_start(autopilot=true)       ← 1 Aufruf statt 4
+    ↓
+fix_plan (in Autopilot enthalten)
+    ↓
+┌───────────────────────────┐
+│  Task N bearbeiten        │
+│  Datei editieren          │
+│  nudge(changed_files=...) │ ← schnell (~0.2 s)
+│  direction prüfen         │
+│  ggf. korrigieren         │
+└─────────┬─────────────────┘
+          │ safe_to_commit?
+          ↓
+    fix_plan(max_tasks=1)    ← nächster Task
+          │ keine Tasks mehr?
+          ↓
+    drift_diff(uncommitted)  ← Abschluss-Verifikation
+          ↓
+    Commit vorbereiten
+```
+
+## Anti-Patterns: Was NICHT tun
+
+| Anti-Pattern | Problem | Stattdessen |
+|---|---|---|
+| `drift_scan` nach jeder Dateiänderung | Volle Repo-Analyse pro Edit (~3–5 s) | `drift_nudge` verwenden (~0.2 s) |
+| `session_start` ohne `autopilot=true` | 4 separate Roundtrips für validate/brief/scan/fix_plan | `autopilot=true` setzen |
+| `fix_plan(max_tasks=5)` oder mehr | Große Response, Agent parst unnötig viel | `max_tasks=1` im Loop verwenden (initiale Übersicht wird von autopilot oder scan-Guidance gesteuert) |
+| Kein `session_id` weitergeben | Jeder Aufruf verliert Kontext, kein Scope-Carry-Over | Immer `session_id` übergeben |
+| `drift_diff` nach jedem Edit | Teurer als nötig für Zwischenfeedback | `nudge` als Inner-Loop, `diff` nur am Ende |
+| Mehrere Findings gleichzeitig fixen | Unklar welche Änderung welchen Effekt hat | Immer ein Finding pro Iteration |
+
+## Verhalten bei `agent_instruction` in Responses
+
+Drift-MCP-Tools geben in jeder Antwort ein Feld `agent_instruction` zurück. **Dieses Feld befolgen.** Es enthält den empfohlenen nächsten Schritt, der zum Session-Zustand passt.
+
+Zusätzlich gibt `next_tool_call` den konkreten nächsten Tool-Aufruf mit Parametern vor. Wenn vorhanden, diesen bevorzugt verwenden.
+
+## Artefakte
+
+Dieser Prompt erzeugt keine separaten Artefakte. Die Änderungen sind die Code-Fixes selbst.

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/.github/skills/drift-effective-usage/SKILL.md

@@ -156,6 +156,33 @@ Notes:
 
 This sequence improves reliability and keeps agent actions policy-aligned.
 
+### Optimized Fix-Loop (Session-Based)
+
+For multi-finding fix workflows, use sessions to eliminate redundant scans:
+
+```
+# 1. Single call replaces validate + brief + scan + fix_plan
+drift_session_start(path=".", autopilot=true)
+
+# 2. Fix first task, then check with nudge (fast, ~0.2s)
+drift_nudge(session_id="<sid>", changed_files="src/foo.py")
+
+# 3. Get next task (always max_tasks=1 to keep responses small)
+drift_fix_plan(session_id="<sid>", max_tasks=1)
+
+# 4. After all tasks: verify once
+drift_diff(session_id="<sid>", uncommitted=true)
+```
+
+Key rules:
+- Always pass `session_id` to every subsequent tool call
+- Use `nudge` (not `scan`) as inner-loop feedback after each edit
+- Use `max_tasks=1` in fix_plan to reduce response size
+- Follow `agent_instruction` and `next_tool_call` fields in responses
+- Run `drift_diff` only as final verification, not after every edit
+
+See `.github/prompts/drift-fix-loop.prompt.md` for the detailed workflow.
+
 ## False Positive Reduction Playbook
 
 1. Confirm repository scope and excludes

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
     rev: v1.5.0
     hooks:
       - id: detect-secrets
-        exclude: "(^|/)(tests/test_hardcoded_secret\\.py|tests/test_insecure_default\\.py|tests/golden/corpus_snapshot\\.json|src/drift/negative_context\\.py|\\.github/instructions/drift-release-automation\\.instructions\\.md)$"
+        exclude: "(^|/)(tests/test_hardcoded_secret\\.py|tests/test_insecure_default\\.py|tests/golden/corpus_snapshot\\.json|src/drift/negative_context\\.py|\\.github/instructions/drift-release-automation\\.instructions\\.md|\\.drift-baseline\\.json)$"
         args:
           - --baseline
           - .secrets.baseline

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/CHANGELOG.md

@@ -2,12 +2,15 @@
 
 ### Added
 
+- Add A2A Agent Card and HTTP serve endpoint (`drift serve`) for agent discovery in multi-agent systems (ADR-026). Exposes `GET /.well-known/agent-card.json` and `POST /a2a/v1` JSON-RPC 2.0 endpoint with 8 core analysis skills. Optional: `pip install drift-analyzer[serve]`.
 - Add machine-readable next-step contracts (`next_tool_call`, `fallback_tool_call`, `done_when`) to all agent-oriented API responses (scan detailed, diff, fix_plan, nudge, brief, negative_context), plus `recovery_tool_call` on error responses, reducing agent hallucinations in tool-call chains (ADR-024).
 - Add `preferred_pattern` field to guardrails and `canonical_refs` list to fix_plan tasks, surfacing positive code references (canonical exemplars, preferred patterns) from existing analysis data so coding agents receive concrete "do this" guidance alongside anti-patterns (ADR-023).
 - Add `--exclude-signals` / `--exclude` option to `drift scan` CLI, `exclude_signals` parameter to the API, and MCP `drift_scan` tool to let callers explicitly exclude dominant or noisy signals (e.g. `MDS`) from returned findings (#173).
 
 ### Fixed
 
+- Add missing `response_profile` docstring entry in `drift_diff` MCP tool, fixing `test_catalog_parameters_have_descriptions` CI failure.
+- Exclude `.drift-baseline.json` from `detect-secrets` scan — fingerprint hex strings are analysis hashes, not secrets.
 - Deduplicate `include` glob patterns in `file_discovery.py` to prevent the same file from being processed and appended multiple times when it matches several include patterns; use lazy `glob()` iterator and reuse `relative_to()` result to reduce redundant I/O.
 - Pass `active_signals` directly to `create_signals()` for early pre-instantiation filtering; add `_SIGNAL_TYPE_VALUE_CACHE` in `signals/base.py` to avoid repeated probe instantiation on the signal-type lookup hot path.
 - Add short-lived in-process git history cache (TTL 120 s, 16-entry LRU) in `fetch_git_history()` to skip redundant `git log` parsing across rapid consecutive scans with unchanged commit history.
@@ -83,7 +86,7 @@
 - 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.6.1] - 2026-04-08
+## [2.6.2] - 2026-04-09
 
 Short version: Signal-filtering for scan, cross-validation fields, and false-positive reductions across multiple signals.
 

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/CITATION.cff

@@ -9,8 +9,8 @@ authors:
 repository-code: "https://github.com/mick-gsk/drift"
 url: "https://mick-gsk.github.io/drift/"
 license: MIT
-version: "2.6.1"
-date-released: "2026-04-07"
+version: "2.6.2"
+date-released: "2026-04-08"
 keywords:
   - static-analysis
   - architectural-drift

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/CONTRIBUTING.md

@@ -200,6 +200,59 @@ Signals must be:
 - **LLM-free** — the core pipeline uses only AST analysis and statistics
 - **Fast** — target < 500ms per 1 000 functions
 
+## Adding ground-truth fixtures
+
+Every signal must have ground-truth fixtures in `tests/fixtures/ground_truth.py`.
+These fixtures drive automated precision/recall measurement via `drift precision`.
+
+### Fixture kinds
+
+| Kind | Purpose | `should_detect` |
+|------|---------|-----------------|
+| `POSITIVE` | Clear true-positive — signal must fire | `True` |
+| `NEGATIVE` | Clear true-negative — signal must not fire | `False` |
+| `BOUNDARY` | Near detection threshold — tests edge behavior | either |
+| `CONFOUNDER` | Looks like a TP but isn't — tests false-positive suppression | `False` |
+
+### Minimum coverage per signal
+
+| Kind | Required |
+|------|----------|
+| Positive (TP) | ≥ 2 |
+| Negative (TN) | ≥ 2 |
+| Boundary | ≥ 1 |
+| Confounder | ≥ 1 |
+
+No signal should ship without at least one TN fixture to prevent FP regressions.
+
+### Workflow
+
+1. Define a `GroundTruthFixture` in the signal's section of `ground_truth.py`
+2. Add it to the `ALL_FIXTURES` list (or the `ALL_FIXTURES.extend(...)` block)
+3. Run `drift precision --signal YOUR_SIGNAL` to verify detection
+4. Run `pytest tests/test_precision_recall.py -k your_fixture_name` to validate
+
+### Using `FileHistoryOverride`
+
+Signals that depend on git history (TVS, SMS) need explicit history data.
+Use `file_history_overrides` on the fixture:
+
+```python
+GroundTruthFixture(
+    name="tvs_example",
+    files={"app/hot.py": "def f(): pass"},
+    expected=[...],
+    file_history_overrides={
+        "app/hot.py": FileHistoryOverride(
+            total_commits=80,
+            change_frequency_30d=25.0,
+        ),
+    },
+)
+```
+
+Fields not set in the override use sensible defaults (see `precision.py:run_fixture`).
+
 ## Code conventions
 
 - Python 3.11+, type annotations everywhere

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drift-analyzer
-Version: 2.6.2
+Version: 2.7.0
 Summary: Deterministic architectural drift detection for AI-accelerated Python repositories through cross-file coherence analysis
 Project-URL: Homepage, https://mick-gsk.github.io/drift/
 Project-URL: Repository, https://github.com/mick-gsk/drift
@@ -174,8 +174,8 @@ Comparison reflects primary design scope per [STUDY.md §9](docs/STUDY.md).
 
 ```bash
 drift analyze --repo .          # see your top findings
-drift explain PFS               # learn what a signal means
 drift fix-plan --repo .         # get actionable repair tasks
+drift check --fail-on none      # add report-only CI discipline
 ```
 
 Add to CI (start report-only):

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/README.md

@@ -90,8 +90,8 @@ Comparison reflects primary design scope per [STUDY.md §9](docs/STUDY.md).
 
 ```bash
 drift analyze --repo .          # see your top findings
-drift explain PFS               # learn what a signal means
 drift fix-plan --repo .         # get actionable repair tasks
+drift check --fail-on none      # add report-only CI discipline
 ```
 
 Add to CI (start report-only):

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/benchmarks/corpus/.drift-cache-golden/history.json

@@ -1,18 +1,18 @@
 [
   {
-    "timestamp": "2026-04-08T09:15:24.768305+00:00",
+    "timestamp": "2026-04-09T09:27:30.251368+00:00",
     "drift_score": 0.373,
     "signal_scores": {
-      "pattern_fragmentation": 0.1445,
       "architecture_violation": 0.1145,
-      "mutant_duplicate": 0.8532,
-      "explainability_deficit": 0.4673,
+      "cognitive_complexity": 0.5357,
+      "dead_code_accumulation": 0.8146,
       "doc_impl_drift": 0.2435,
-      "test_polarity_deficit": 0.1734,
+      "explainability_deficit": 0.4673,
       "guard_clause_deficit": 0.4698,
+      "mutant_duplicate": 0.8532,
       "naming_contract_violation": 0.3469,
-      "cognitive_complexity": 0.5357,
-      "dead_code_accumulation": 0.8146
+      "pattern_fragmentation": 0.1445,
+      "test_polarity_deficit": 0.1734
     },
     "total_files": 26,
     "total_findings": 64,

drift_analyzer-2.7.0/decisions/ADR-026-a2a-agent-card-http-serve.md

@@ -0,0 +1,72 @@
+---
+id: ADR-026
+status: proposed
+date: 2026-04-08
+supersedes:
+---
+
+# ADR-026: A2A Agent Card und HTTP-Serve-Endpunkt
+
+## Kontext
+
+Drift kommuniziert aktuell ausschließlich über stdio (MCP-Protokoll) und CLI. In Multi-Agenten-Systemen, die dem A2A-Standard (Agent-to-Agent Protocol v1.0) folgen, ist ein standardisiertes Discovery-Manifest (`/.well-known/agent-card.json`) erforderlich, damit Orchestratoren Drift automatisch erkennen und kontaktieren können. Ohne HTTP-Endpunkt ist kein A2A-Discovery möglich.
+
+## Entscheidung
+
+1. **Neuer optionaler HTTP-Server** via `drift serve` CLI-Subcommand.  
+   Framework: FastAPI + uvicorn als optionale Dependencies (`pip install drift-analyzer[serve]`).
+
+2. **Agent Card** unter `GET /.well-known/agent-card.json` nach A2A v1.0.  
+   Exponiert 8 Kern-Analyse-Skills: scan, diff, explain, fix_plan, validate, nudge, brief, negative_context.
+
+3. **A2A JSON-RPC 2.0 Endpunkt** unter `POST /a2a/v1`.  
+   Skill-Dispatch via `skillId` in message metadata oder `skill`-Feld im data-Part.
+
+4. **Security-Defaults**: Host `127.0.0.1` (localhost-only), kein Auth in v1.  
+   Netzwerk-Exposure nur via explizitem `--host 0.0.0.0`.
+
+5. **Kein Streaming** in v1 (`capabilities.streaming: false`).
+
+### Was explizit nicht getan wird
+
+- Session-Management- und Task-Queue-Tools (9 von 17 MCP-Tools) werden nicht als A2A-Skills exponiert.
+- Kein Authentifizierungsmechanismus in v1 — Risk wird im STRIDE-Modell dokumentiert.
+- Kein A2A Push-Notification-Support.
+- Kein automatischer HTTPS/TLS — wird dem Deployment (Reverse Proxy) überlassen.
+
+## Begründung
+
+### Warum FastAPI + uvicorn (statt stdlib http.server)
+
+- Typed request/response-Modelle via Pydantic (bereits Core-Dependency)
+- OpenAPI-Schema erhalten Nutzer gratis
+- FastAPI `TestClient` ermöglicht synchrone Tests ohne laufenden Server
+- stdlib `http.server` bietet kein Typed Schema, keine async-Unterstützung, keine Middleware
+
+### Warum JSON-RPC statt REST pro Skill
+
+- A2A v1.0 spezifiziert JSON-RPC 2.0 als primäres Protokoll-Binding
+- Ein einzelner `/a2a/v1`-Endpunkt mit Skill-Dispatch ist A2A-konform
+- Separate REST-Routen pro Skill wären nicht A2A-kompatibel
+
+### Warum nur 8 von 17 Tools
+
+- Die 8 Kern-Analyse-Tools sind für Orchestratoren relevant (stateless Analyse)
+- Session- und Task-Queue-Tools (9 weitere) sind MCP-spezifische Workflow-Hilfen, die im A2A-Kontext keinen Mehrwert bieten
+- Erweiterbar in v2 falls Bedarf entsteht
+
+## Konsequenzen
+
+- **Neue optionale Dependencies**: `fastapi>=0.110.0,<1.0` und `uvicorn[standard]>=0.28.0` im `[serve]`-Extra.
+- **Neuer Trust Boundary**: HTTP-Clients können über Netzwerk auf Drift-Analyse zugreifen. Default localhost-only mitigiert Remote-Exposure.
+- **Repo-Path im Request**: A2A-Handler müssen Pfad-Validierung durchführen (Path-Traversal-Schutz).
+- **STRIDE + Risk Register**: Pflicht-Updates unter `audit_results/` (Policy §18).
+- **Kein Breaking Change**: Bestehende CLI und MCP-Nutzung bleiben unverändert; `serve` ist rein additiv.
+
+## Validierung
+
+- [ ] `pytest tests/test_a2a_serve.py` — alle Tests grün (Agent Card, JSON-RPC Dispatch, Fehlercodes)
+- [ ] `curl http://localhost:8080/.well-known/agent-card.json` liefert valides A2A v1.0 JSON
+- [ ] A2A JSON-RPC POST mit `scan`-Skill liefert korrekte Analyse-Antwort
+- [ ] `mypy src/drift/serve/` + `ruff check` fehlerfrei
+- [ ] `drift serve` ohne installiertes FastAPI zeigt Installations-Hinweis

drift_analyzer-2.7.0/decisions/ADR-027-finding-status-for-suppression-transparency.md

@@ -0,0 +1,49 @@
+---
+id: ADR-027
+status: proposed
+date: 2026-04-08
+supersedes:
+---
+
+# ADR-027: Expliziter Finding-Status fuer Suppression-Transparenz
+
+## Kontext
+
+Drift blendet aktuell inline unterdrueckte Findings aus der primaeren Finding-Liste aus und zeigt nur einen Zaehler (`suppressed_count`). Dadurch kann in automatisierten Agenten-Workflows der Eindruck entstehen, dass Drift real reduziert wurde, obwohl Findings nur unterdrueckt wurden.
+
+## Entscheidung
+
+1. Wir fuehren additive Statusfelder auf `Finding` ein:
+   - `status` (`active`, `suppressed`, `resolved`)
+   - `status_set_by`
+   - `status_reason`
+2. Inline-Suppressions markieren Findings explizit als `suppressed` mit Herkunft `inline_comment`.
+3. `RepoAnalysis` traegt suppresste Findings in einer separaten Liste (`suppressed_findings`) fuer maschinenlesbare Transparenz.
+4. JSON-Output erweitert sich additiv um:
+   - Statusfelder pro Finding
+   - `findings_suppressed` (nur Full-JSON)
+   - `compact_summary.suppressed_total`
+
+### Was explizit nicht getan wird
+
+- Keine Aenderung der Severity-Gate-Semantik in dieser Iteration.
+- Kein neues Suppression-Policy-Format in dieser Iteration.
+- Keine breaking schema changes; nur additive Felder.
+
+## Begruendung
+
+Die Trennung von `active` und `suppressed` ist die kleinste technisch robuste Aenderung, um False-Negative durch Suppression sichtbar zu machen, ohne bestehende Konsumenten zu brechen. Additive Felder erlauben schrittweise Adoption in CI und Agenten.
+
+## Konsequenzen
+
+- JSON-Schema-Minor wird auf `1.1` angehoben.
+- Downstream-Consumer koennen weiterhin nur `findings` lesen; neue Transparenz ist opt-in.
+- Grundlage fuer spaetere CI-Enforcement-Regeln (`no-new-suppressions`, Suppression-Budget) wird vorbereitet.
+
+## Validierung
+
+- [ ] `pytest tests/test_suppression.py -q --maxfail=1`
+- [ ] `pytest tests/test_json_output.py -q --maxfail=1`
+- [ ] `pytest tests/test_baseline.py -q --maxfail=1`
+- [ ] `drift analyze --repo . --format json --exit-zero` enthaelt Statusfelder und `findings_suppressed`
+- [ ] Lernzyklus-Ergebnis (Policy): bestaetigt | widerlegt | unklar | zurueckgestellt

drift_analyzer-2.7.0/decisions/ADR-028-analyzer-warning-channel.md

@@ -0,0 +1,86 @@
+---
+id: ADR-028
+status: proposed
+date: 2026-04-09
+supersedes:
+---
+
+# ADR-028: Analyzer Warning Channel via BaseSignal Instance Field
+
+## Kontext
+
+`BaseSignal.analyze()` gibt `list[Finding]` zurück. Es existiert kein Mechanismus,
+um Nicht-Finding-Informationen (z. B. "Signal wurde übersprungen, weil
+Voraussetzungen fehlen") aus einem Signal herauszutransportieren.
+
+Konkreter Auslöser: `TemporalVolatilitySignal` gibt bei leerem `file_histories`-Dict
+still eine leere Liste zurück. Nutzer ohne `.git`-Verzeichnis oder mit flachem Clone
+erhalten kein Feedback, warum TVS stumm bleibt.
+
+## Entscheidung
+
+Warnungen werden über ein Instanzfeld auf `BaseSignal` transportiert:
+
+1. **Neues Dataclass `AnalyzerWarning`** in `drift/models.py`:
+   - `signal_type: str` — Quellsignal
+   - `message: str` — menschenlesbarer Text
+   - `skipped: bool = True` — ob das Signal übersprungen wurde
+
+2. **`BaseSignal` erhält:**
+   - `_warnings: list[AnalyzerWarning]` (initialisiert in `__init__`)
+   - `emit_warning(message, *, skipped=True)` — Hilfsmethode zum Anhängen
+
+3. **Engine/Runner** liest `signal._warnings` nach jedem `analyze()`-Aufruf
+   und sammelt sie zentral.
+
+4. **CLI** gibt Warnungen als `⚠ Warning`-Zeilen nach der Finding-Ausgabe aus,
+   nicht als Findings.
+
+### Was explizit nicht getan wird
+
+- Keine Änderung der `analyze()`-Signatur
+- Keine Breaking Change an `AnalysisContext`
+- Kein neuer Rückgabetyp (z. B. `AnalysisResult(findings, warnings)`)
+- Warnungen fließen nicht in Scoring oder Severity-Berechnung ein
+
+## Begründung
+
+### Verworfene Alternative: `AnalysisContext.warnings`
+
+Signale erhalten keinen Context-Parameter in `analyze()`. Der Context müsste
+über `bind_context()` gespeichert und in `analyze()` via `self._analysis_context`
+zugänglich gemacht werden. Das erfordert Änderungen an allen bestehenden
+`bind_context()`-Callsites und fügt dem Context weitere Verantwortlichkeiten
+hinzu.
+
+### Verworfene Alternative: Neuer Rückgabetyp
+
+`analyze()` → `AnalysisResult(findings, warnings)` bricht alle bestehenden
+Signal-Implementierungen und alle Callsites. Hoher Aufwand, geringer
+Zusatznutzen gegenüber dem Instanzfeld.
+
+### Gewählter Ansatz: Instanzfeld
+
+- Kein Breaking Change
+- Rückwärtskompatibel — Signale ohne Warnungen funktionieren unverändert
+- Engine-Integration ist ein Einzeiler pro Signal-Aufruf
+- Einfach testbar
+
+## Konsequenzen
+
+- Jedes Signal kann Warnungen emittieren, ohne API-Änderung
+- Engine-Code muss nach `signal.analyze()` zusätzlich `signal._warnings` lesen
+- Warnings accumulate pro Signal-Instanz; bei Wiederverwendung müsste `_warnings`
+  geleert werden (aktuell kein Anwendungsfall, da Instanzen pro Lauf erzeugt werden)
+- Der precision-Runner und die CLI müssen Warnungen separat weiterreichen
+
+## Validierung
+
+```bash
+# TVS emittiert Warning bei leerem file_histories
+pytest tests/test_precision_recall.py -v -k tvs_new_file
+# Neuer CLI-Befehl zeigt Warnungen
+drift precision --signal TVS
+```
+
+Lernzyklus-Ergebnis: zurückgestellt (wird nach erstem Produktiveinsatz bewertet).

{drift_analyzer-2.6.2 → drift_analyzer-2.7.0}/docs/STUDY.md

@@ -1,9 +1,13 @@
 # STUDY.md — Evaluating Architectural Drift Detection in Real-World Python Projects
 
+> **Baseline update (2026-04-09, v2.7 KPI Roadmap):** First full-model precision/recall baseline on the current 15-signal scoring model (14 scoring-active + TVS at weight 0.0). Ground-truth fixture suite expanded to 110 fixtures covering 16 signal types (was: 105 fixtures, 13 signals). **New coverage:** CCC (Co-Change Coupling) — TP/TN fixtures using injected CommitInfo data; COD (Cohesion Deficit) — boundary TN added (now ≥5 fixtures); ECM (Exception Contract Drift) — TN fixture (TP deferred: requires git-backed integration fixture). **Result:** All 16 evaluated signals at P=1.00 R=1.00 F1=1.00 on ground-truth fixtures; macro-average F1=1.00. Mutation benchmark: 17/17 = 100% recall (10/14 scoring signals covered). CI aggregate F1 gate raised from 0.50 → 0.60. CCC added to per-signal precision gates at 0.50. **Limitations:** Fixture P/R measures in-vitro signal correctness, not real-world precision on diverse codebases. Oracle-based precision (§3) remains at v0.5 baseline. Known gaps: ECM has 0 TP fixtures; CCC/ECM/COD/BAT/NBV missing mutation patterns. Evidence: `benchmark_results/v2.7.0_precision_recall_baseline.json`.
+
 > **Versioning note (2026-04-05):** The package version in this repository is drift v2.5.4. Most quantitative benchmark artifacts referenced in this document were generated with drift v0.5.0 unless a later dated section states otherwise. The current production model exposes 23 configured signals, of which 15 are scoring-active and 8 remain report-only pending broader validation. This file therefore documents a historical evidence baseline and must not be read as a full description of the current live signal model. As of v2.5.0 the `scan` API and CLI command expose a `strategy` parameter (`diverse` / `top-severity`) that controls finding selection.
 
 > **Feature update (2026-04-07, v2.5.4):** AVS `avs_co_change` precision hardening via FTA-driven three-MCS fix (ADR-018): self-analysis avs_co_change findings 20→0 (score 0.522→0.501, total findings 345→330). (1) Same-directory guard suppresses sister-file co-evolution in package directories; root-level pairs preserved. (2) `known_files` built from `filtered_prs` (consistent with import graph) eliminates test-source FPs. (3) Commit-size discount `1/(n-1)` in `build_co_change_pairs` reduces bulk/sweep-commit inflation. Mutation benchmark: AVS recall 100% (2/2), overall 94% (16/17). 5 regression tests added. Evidence: `benchmark_results/v2.5.4_avs_co_change_precision_hardening_feature_evidence.json`.
 
+> **Feature update (2026-04-08):** Added A2A Agent Discovery support via `drift serve` (ADR-026): optional FastAPI/uvicorn HTTP server exposing `GET /.well-known/agent-card.json` (A2A v1.0 Agent Card) and `POST /a2a/v1` (JSON-RPC 2.0 dispatch) with 8 core skills (`scan`, `diff`, `explain`, `fix_plan`, `validate`, `nudge`, `brief`, `negative_context`). Security posture: localhost-only default bind (`127.0.0.1`), path normalization/validation in request router. Evidence: `benchmark_results/v2.7.0_a2a_agent_card_feature_evidence.json`; tests: `tests/test_a2a_serve.py` (15 passed).
+
 > **Feature update (2026-04-07):** DIA FTA v2 eliminates all remaining self-analysis false positives (DIA findings 2→0 on own repo): (1) `_AUXILIARY_DIRS` extended with `artifacts` and `work_artifacts` to cover CI/build artifact and working directories; (2) illustrative path examples in ADR-017 moved from inline codespans to fenced code blocks so ADR scanning's `trust_codespans=True` no longer extracts them as phantom refs. FTA v2 root-cause chain: IE-4 (BE-8a) + IE-5a. 76/76 DIA unit tests green (3 new regression tests); 97/97 precision/recall fixtures unaffected. Evidence: `audit_results/risk_register.md` (RISK-SIG-2026-04-08-191).
 
 > **Feature update (2026-04-05):** v2.5.0 extends `drift scan` with two agent-usability improvements. First, **signal filtering**: new `--exclude-signals` and `--max-per-signal` parameters on CLI, API, and MCP let callers suppress dominant signals or cap per-signal finding volume for balanced, token-efficient result lists (#173). ADR-013 documents the design decision. Second, **cross-validation fields**: all scan findings now include `signal_abbrev`, `signal_id`, `signal_type`, `severity_rank` (5=critical … 1=info), and a deterministic `fingerprint`; the response carries a top-level `cross_validation` block with field and score-range documentation for machine consumption (#171). DIA: suppress missing-README for bootstrap-sized repos (≤1 Python file). Evidence: `benchmark_results/v2.5.0_feature_evidence.json`; tests: `tests/test_scan_diversity.py`, `tests/test_agent_native_cli.py`, `tests/test_analysis_edge_cases.py`.
@@ -46,10 +50,11 @@
 
 ## Executive Summary
 
-### Public Claims Safe To Repeat As Of 2026-03-30
+### Public Claims Safe To Repeat As Of 2026-04-09
 
 - The package version in this repository is drift v2.5.4. The core benchmark corpus summarized below is the v0.5.0 evidence baseline.
 - The v0.5 baseline composite score used 6 scoring signals. The current model exposes 23 configured signals, with 15 scoring-active and 8 report-only pending broader validation; quantitative precision/recall claims in this study apply only to the historical 6-signal model and have not been revalidated for the current live model.
+- **v2.7 ground-truth baseline (2026-04-09):** 110 fixtures across 16 signal types yield P=1.00 R=1.00 F1=1.00 (macro) on the current 15-signal model. This measures in-vitro fixture correctness, not real-world oracle precision. Evidence: `benchmark_results/v2.7.0_precision_recall_baseline.json`.
 - The current study corpus still covers 15 real-world repositories.
 - All analysis is deterministic; no LLM is used in the detector pipeline.
 
@@ -92,7 +97,7 @@ $$S_i = \frac{\sum f_{ij}}{n_i} \cdot \min\!\left(1,\; \frac{\ln(1 + n_i)}{\ln(1
 
 DIA, BEM, TPD, and GCD are included in the analysis output but contribute 0.0 to the composite score. They are Phase 2 signals with known precision limitations (see §3.1 for DIA; see [ADR-007](adr/007-consistency-proxy-signals.md) for BEM/TPD/GCD).
 
-**Current codebase note (v2.5.4):** The live model exposes 23 configured signals, of which 15 are scoring-active and 8 remain report-only pending broader validation. The table above documents the v0.5 baseline only. Precision and recall claims in this study have not been revalidated for the current live model.
+**Current codebase note (v2.7 baseline):** The live model exposes 23 configured signals, of which 14 are scoring-active (TVS weight reduced to 0.0) and 9 remain report-only. Ground-truth fixture evaluation (110 fixtures, 16 signal types) yields P=1.00 / R=1.00 / F1=1.00 macro-average. 10/14 scoring-active signals have mutation coverage (17/17 = 100% recall). The table above documents the v0.5 baseline only. See `benchmark_results/v2.7.0_precision_recall_baseline.json` for the full current-model baseline.
 
 ### 1.2 Repository Selection