sourcecode 1.30.13__tar.gz → 1.30.14__tar.gz

sourcecode-1.30.14/.continue-here.md

@@ -0,0 +1,231 @@
+# Continue Here — atlas-cli sesión 14
+
+**Paused:** 2026-05-17 (sesión 14)
+**Repo:** `/Users/user/Downloads/atlas-cli`
+**Branch:** master
+**Working tree:** 4 ficheros modificados, SIN commit (trabajo listo para commit)
+
+---
+
+## Trabajo de esta sesión (NO commiteado)
+
+Esta sesión completó 3 tareas sobre `repository_ir.py`. Todo el trabajo incluye la sesión 13 (stable IDs) + sesión 14 (route diffing + reverse graph). Hacer UN solo commit con todo.
+
+---
+
+### Tarea 1 (sesión 13): Rearchitecture Directive — eliminar lenguaje especulativo
+
+**Ficheros:** `src/sourcecode/prepare_context.py`, `src/sourcecode/flow_analyzer.py`
+
+| Eliminado | Reemplazado con |
+|---|---|
+| `_ARTIFACT_CHANGE_EFFECT` con "may affect/inferred from role" | Labels estructurales: `"HTTP routing layer (request-to-handler mapping)"` |
+| `"type": "inferred"` en `_role_obj` | `{basis, has_annotation_signal, has_symbol_signal}` |
+| `"confidence": _f_conf` en runtime change entries | `"evidence_completeness"` del impact dict |
+| `_score_to_confidence()` function | Deleted completely |
+| `"confidence": score_band` en `impact_score_per_file` | `"evidence": {has_reverse_edges, has_route_diff, has_security_diff, has_wiring_evidence}` |
+| `behavioral_changes` sin graph evidence | Gateado en `has_graph_evidence == True` |
+
+---
+
+### Tarea 2 (sesión 13): Stable Symbol Identities
+
+**Ficheros:** `src/sourcecode/repository_ir.py`, `tests/test_repository_ir.py`
+
+**Nuevas funciones helper:**
+- `_normalize_type_name(raw)` — strip annotations/modifiers/param names → solo tipo
+- `_parse_param_types(params_str)` — `"Long id, String name"` → `["Long", "String"]` (depth-aware, maneja generics)
+- `_compute_stable_id(package, class_simple, kind, name, param_types, return_type)` — ID determinista
+
+**`SymbolRecord`** — 8 nuevos campos: `stable_id`, `symbol_kind`, `canonical_name`, `source_file`, `signature`, `param_types`, `return_type`, `annotation_values`
+
+**`symbol_kind` values:** `enum`, `annotation`, `endpoint`, `bean`, `constructor` (además de `class`, `interface`, `method`, `field`)
+
+**Formato stable_id:**
+```
+{package}:{class_simple}:{kind}:{name}[:{(param_types)}[:{return_type}]]
+```
+
+---
+
+### Tarea 3 (sesión 14): Spring Route-Surface Diffing
+
+**Ficheros:** `src/sourcecode/repository_ir.py`, `tests/test_repository_ir.py`
+
+**Qué se implementó:**
+
+| Componente | Cambio |
+|---|---|
+| `_ANN_WITH_ARGS_RE` | Captura args de anotaciones (`@GetMapping("/path")`) |
+| `SymbolRecord.annotation_values` | `dict[str, str]` — ann_name → raw args string |
+| `_HTTP_METHOD_MAP` | `@GetMapping → GET` etc. |
+| `_parse_route_path/http_method/extras` | Extraen path, method, produces/consumes |
+| `_is_route_symbol / _route_annotation_name / _enclosing_class` | Helpers de routes |
+| `_symbol_fingerprint` | Incluye valores de route annotations — cambio de path → fingerprint cambia |
+| `_diff_symbols` | Detecta `route_surface_change` antes de `annotation_change` genérico |
+| `_DIFF_INTENSITY_MAP` | `route_surface_change: 1.0` |
+| `_diff_routes` | Diff estructurado: old/new path, HTTP method, produces/consumes, evidence dict |
+| `_assemble` | Emite `route_surface: [...]` |
+
+**Output cuando route cambia:**
+```json
+{
+  "route_surface": [{
+    "symbol": "com.example.HealthController#health",
+    "controller": "com.example.HealthController",
+    "route_surface_changed": true,
+    "old_route": "/health",
+    "new_route": "/health/v3",
+    "stable_id": "com.example:HealthController:endpoint:health:():String",
+    "evidence": {
+      "annotation_value_changed": true,
+      "mapping_annotation": "RequestMapping",
+      "old_value": "/health",
+      "new_value": "/health/v3"
+    }
+  }]
+}
+```
+
+---
+
+### Tarea 4 (sesión 14): Reverse Impact Graph
+
+**Ficheros:** `src/sourcecode/repository_ir.py`, `tests/test_repository_ir.py`
+
+**Problema raíz resuelto:** `_propagate_impact` traversaba grafo hacia ADELANTE (si A cambia → impacta B que A usa). Incorrecto. Impact analysis necesita grafo INVERSO (si A cambia → impacta quién DEPENDE de A).
+
+**Qué se implementó:**
+
+| Componente | Cambio |
+|---|---|
+| `contained_in` edges | `_build_relations` emite `method/field → enclosing class` |
+| `_build_reverse_adjacency` | Invierte todas las relaciones (excluye `annotated_with`, `mapped_to`) |
+| `_EDGE_REASON_TEMPLATES` + `_edge_reason` | Edge → string legible |
+| `_bfs_impact_with_paths` | Reemplaza `_propagate_impact`. BFS en grafo inverso con path tracking |
+| `enclosing_seeds` param | Omite `contained_in` edges al sembrar desde clase enclosing para no incluir métodos hermanos |
+| `reverse_graph` en output | `{target_fqn: {edge_type: [from_fqn, ...]}}` — índice para agentes |
+
+**Cadena de propagación funcional:**
+```
+UserRepository#findById cambia →
+  [1] UserService         ← "UserService depends on UserRepository (import)"
+  [2] UserService#getUser ← "... is a member of UserService"
+  [2] OrderController     ← "OrderController depends on UserService (import)"
+  [3] OrderController#getUser ← "... is a member of OrderController"
+```
+
+`UserRepository#save` (hermano, sin cambios) correctamente excluido.
+
+**Cada entidad impactada expone:**
+```json
+{
+  "entity": "com.example.web.OrderController",
+  "depth": 2,
+  "impact_score": 0.0113,
+  "via": "com.example.service.UserService",
+  "graph_path": ["com.example.repo.UserRepository", "com.example.service.UserService", "com.example.web.OrderController"],
+  "included_because": [
+    "com.example.service.UserService depends on com.example.repo.UserRepository (import)",
+    "com.example.web.OrderController depends on com.example.service.UserService (import)"
+  ]
+}
+```
+
+---
+
+## Estado de tests
+
+```
+920 passed, 3 skipped   (era 885 antes de sesión 13)
+```
+
+Pre-existing failures (no tocar):
+- `tests/test_block2_coverage.py` — bug `DocRecord` en `doc_analyzer.py`
+- `tests/test_dependency_analyzer_node_python.py::test_python_requirements_without_lockfile_keeps_declared_versions`
+
+---
+
+## Cambios sin commitear
+
+```
+src/sourcecode/flow_analyzer.py       |  22 +-
+src/sourcecode/prepare_context.py     | 113 ++++---
+src/sourcecode/repository_ir.py       | 522 +++++++++++++++++++++++++++++--
+tests/test_repository_ir.py           | 635 +++++++++++++++++++++++++++++++++++++-
+```
+
+**Para commitear TODO (primera acción al retomar):**
+```bash
+cd /Users/user/Downloads/atlas-cli
+git add src/sourcecode/flow_analyzer.py \
+        src/sourcecode/prepare_context.py \
+        src/sourcecode/repository_ir.py \
+        tests/test_repository_ir.py
+
+git commit -m "feat: stable IDs + route-surface diffing + reverse impact graph
+
+- Stable deterministic IDs for all symbol kinds (class/interface/enum/
+  method/constructor/field/endpoint/bean) — survives formatting/body changes
+- symbol_kind, canonical_name, signature, annotation_values on all graph nodes
+- Replace heuristic confidence scoring with evidence completeness dicts
+- Remove speculative behavioral prose (may affect / inferred from role)
+- Gate behavioral_changes on has_graph_evidence
+- Route-surface diffing: annotation value changes detected as route_surface_change;
+  evidence dict with old/new path, HTTP method, produces/consumes
+- Reverse impact graph: BFS on inverted graph; each impacted symbol carries
+  graph_path + included_because explaining the dependency chain
+- contained_in edges expose method/field → class membership for propagation
+- reverse_graph output: {target: {edge_type: [from_fqns]}} for agent queries
+- 35 new acceptance tests (920 total passing)"
+```
+
+---
+
+## Pendientes (próxima sesión)
+
+### Prioridad alta
+1. **Spring bean wiring graph** — `_build_relations` ya emite `injects` edges para `@Autowired` fields. Falta: trazar grafo completo `@Configuration → @Bean → @Autowired` y exponer como `wiring_graph` en IR output.
+
+2. **Smoke test en repo spring-boot real:**
+   ```bash
+   cd ~/Documents/workspace/spring-boot-realworld-example-app
+   sourcecode repo-ir . --since HEAD~1 2>/dev/null | python3 -c "
+   import json, sys
+   d = json.load(sys.stdin)
+   print('schema:', d['schema_version'])
+   print('nodes:', len(d['graph']['nodes']))
+   print('route_surface:', d.get('route_surface', []))
+   rg = d.get('reverse_graph', {})
+   print('reverse_graph keys:', len(rg))
+   "
+   ```
+
+3. **Transaction boundary tracking** — `@Transactional` ya detectado. Falta: emitir `transactional_boundary` edges.
+
+### Prioridad media
+4. **`_diff_routes` para `@RequestMapping` en clase** — si class-level mapping cambia (`/api/v1` → `/api/v2`), debería propagarse a todos los endpoints del controller.
+
+5. **Tests unitarios para `_classify_diff_severity`** — sin cobertura
+
+---
+
+## Para retomar
+
+```bash
+cd /Users/user/Downloads/atlas-cli
+git log --oneline -5   # último commit: 31aa91a
+git status             # debe mostrar 4 ficheros modificados sin trackear
+
+python3 -m pytest tests/ \
+  --ignore=tests/test_block2_coverage.py \
+  --ignore=tests/test_dependency_analyzer_node_python.py \
+  -q
+# Expected: 920 passed, 3 skipped
+
+# Primera acción: commitear (comando arriba)
+```
+
+---
+
+*Pausado 2026-05-17 sesión 14 — gsd:pause-work*

{sourcecode-1.30.13 → sourcecode-1.30.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.13
+Version: 1.30.14
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -221,7 +221,7 @@ Description-Content-Type: text/markdown
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.13-blue)
+![Version](https://img.shields.io/badge/version-1.30.14-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +257,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.13
+# sourcecode 1.30.14
 ```
 
 ---

{sourcecode-1.30.13 → sourcecode-1.30.14}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.13-blue)
+![Version](https://img.shields.io/badge/version-1.30.14-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.13
+# sourcecode 1.30.14
 ```
 
 ---

{sourcecode-1.30.13 → sourcecode-1.30.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.30.13"
+version = "1.30.14"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.30.13 → sourcecode-1.30.14}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.30.13"
+__version__ = "1.30.14"

{sourcecode-1.30.13 → sourcecode-1.30.14}/src/sourcecode/flow_analyzer.py

@@ -381,27 +381,27 @@ def _impact_descriptions(
 
     if changed_type in _REPO_ARTIFACT_TYPES:
         items.append(_impact_item(
-            f"{domain} persistence may be affected (inferred from path)" if domain else "persistence may be affected (inferred from path)",
-            f"{changed_class} classified as repository from path",
+            f"{domain} persistence layer modified" if domain else "persistence layer modified",
+            f"{changed_class} classified as {changed_type} (artifact_type evidence)",
             certainty,
         ))
     elif changed_type in _SERVICE_ARTIFACT_TYPES:
         if end_state == "DB write":
             items.append(_impact_item(
-                f"{domain} persistence may be affected (repository with DB write in path)" if domain else "persistence may be affected (repository with DB write in path)",
-                f"{changed_class} delegates to repository with DB write",
+                f"{domain} service layer: DB write in call path" if domain else "service layer: DB write in call path",
+                f"{changed_class} delegates to repository with DB write (code evidence)",
                 certainty,
             ))
         else:
             items.append(_impact_item(
-                f"{domain} behavior may change" if domain else "behavior may change",
-                f"{changed_class} is a service in path",
+                f"{domain} service layer modified" if domain else "service layer modified",
+                f"{changed_class} is a service (artifact_type={changed_type})",
                 certainty,
             ))
     else:
         items.append(_impact_item(
-            f"{domain} behavior may change" if domain else "behavior may change",
-            f"{changed_class} is in path",
+            f"{domain} component modified" if domain else "component modified",
+            f"{changed_class} found in traced call path (artifact_type={changed_type})",
             certainty,
         ))
 
@@ -440,14 +440,14 @@ def _impact_descriptions_for_controller(
                 domain = d
                 break
         items.append(_impact_item(
-            f"{domain} persistence may be affected (repository with DB write in path)" if domain else "data persistence may be affected (repository with DB write in path)",
-            "repository with DB write detected in path",
+            f"{domain} persistence layer: repository with DB write in call path" if domain else "persistence layer: repository with DB write in call path",
+            "repository with DB write detected in traced call path (code evidence)",
             certainty,
         ))
     else:
         items.append(_impact_item(
-            "request handler behavior may change",
             "controller entry point modified",
+            "controller entry point is in changed files (direct diff evidence)",
             certainty,
         ))
 

{sourcecode-1.30.13 → sourcecode-1.30.14}/src/sourcecode/prepare_context.py

@@ -539,23 +539,23 @@ def _read_code_signal_evidence(root: Path, file_path: str, artifact_type: str) -
 
 
 _ARTIFACT_CHANGE_EFFECT: dict[str, str] = {
-    "entrypoint":     "may affect application startup, CLI entry, or framework bootstrap — all request flows may be affected (inferred from role)",
-    "controller":     "may alter HTTP routing, API contract, or response shape — API consumers may be affected (inferred from role)",
-    "service":        "may change business rules, transaction scope, or orchestration logic — callers and dependents may be affected (inferred from role)",
-    "repository":     "may modify persistence queries or data access patterns — verify data consistency and service layer (inferred from role)",
-    "mapper":         "may alter SQL-to-object binding or query templates — data shape and repositories may be affected (inferred from role)",
-    "security":       "may change authentication flow, access control rules, or session handling — all secured endpoints may be affected (inferred from role)",
-    "spring_config":  "may modify bean wiring, datasource, or framework-wide settings — wired beans potentially affected (inferred from role)",
-    "spring_profile": "may change environment-specific overrides — behavior may differ per active profile (inferred from role)",
-    "config":         "may adjust configuration values — all modules reading this config may be affected (inferred from role)",
-    "build_manifest": "changes dependencies, plugins, or project structure — compile-time and runtime classpath affected",
-    "db_migration":   "modifies database schema — existing queries, mappings, and constraints may break",
-    "domain_model":   "may alter entity structure — may cascade to repositories, DTOs, serializers, and mappers (inferred from role)",
-    "dto":            "may change data transfer contract — serialization and API consumers may break (inferred from role)",
-    "test":           "modifies test coverage or test behavior — no production code affected",
-    "documentation":  "updates documentation only — no runtime impact",
-    "ide_noise":      "IDE/tooling artifact — no application impact",
-    "source":         "modifies application source — artifact role derived from file path structure",
+    "entrypoint":     "application entrypoint (framework bootstrap / CLI handler)",
+    "controller":     "HTTP routing layer (request-to-handler mapping)",
+    "service":        "business logic layer (@Service component)",
+    "repository":     "data access layer (persistence queries / ORM)",
+    "mapper":         "SQL-object mapping layer (MyBatis mapper / query template)",
+    "security":       "security component (authentication / access control configuration)",
+    "spring_config":  "Spring @Configuration class (bean definitions / datasource wiring)",
+    "spring_profile": "Spring profile override (environment-specific configuration)",
+    "config":         "configuration file (application properties / environment values)",
+    "build_manifest": "build manifest (dependency and plugin configuration)",
+    "db_migration":   "database schema migration (DDL change pending execution)",
+    "domain_model":   "domain entity (@Entity / value object)",
+    "dto":            "data transfer object (serialization contract)",
+    "test":           "test file (no production code modified)",
+    "documentation":  "documentation file (no runtime impact)",
+    "ide_noise":      "IDE/tooling artifact (no application impact)",
+    "source":         "application source (artifact role requires annotation inspection)",
 }
 
 # Maps frontend symptom keywords → backend terms likely to contain the root cause.
@@ -1037,7 +1037,7 @@ class TaskContextBuilder:
             _pr_review_hotspots = sorted(
                 [f for f, cls in _pr_changed_cls.items()
                  if not cls["is_noise"] and cls["artifact_type"] != "build_manifest"],
-                key=lambda f: (_delta_impact_score_per_file.get(f) or {}).get("score", 0.0),
+                key=lambda f: (_delta_impact_score_per_file.get(f) or {}).get("_rank_score", 0.0),
                 reverse=True,
             )[:8]
 
@@ -1123,33 +1123,29 @@ class TaskContextBuilder:
                 _has_code_ev = any(e["type"] in ("annotation", "import") for e in _evidence)
                 _has_symbol_ev = any(e["type"] == "symbol" for e in _evidence)
                 _role_basis = "annotation" if _has_code_ev else ("symbol" if _has_symbol_ev else "git_diff_only")
-                _cls_conf = _f_cls["confidence"]
                 _role_obj = {
-                    "type": "inferred",
-                    "confidence": "medium" if (_has_code_ev or (_has_symbol_ev and _cls_conf == "high")) else "low",
                     "basis": _role_basis,
+                    "has_annotation_signal": _has_code_ev,
+                    "has_symbol_signal": _has_symbol_ev,
                 }
 
-                # File confidence: from structured impact entry
-                _impact_entry = _delta_impact_score_per_file.get(_f) or {}
-                _f_conf = _impact_entry.get("confidence", "low")
                 _diff_source = (
                     DiffSourceType.GIT_RANGE.value if _f in _committed_set
                     else DiffSourceType.WORKTREE_UNSTAGED.value if _f in _uncommitted_set
                     else "unknown"
                 )
+                _impact_entry = _delta_impact_score_per_file.get(_f) or {}
                 _entry = {
                     "path": _f,
                     "diff_source": _diff_source,
                     "role": _role_obj,
-                    "confidence": _f_conf,
                     "artifact_type": _f_atype,
                     "evidence": _evidence,
                     "change_effect": {
-                        "statement": _ARTIFACT_CHANGE_EFFECT.get(_f_atype, "may modify application logic (role inferred from path)"),
-                        "truth_level": "inferred",
-                        "confidence": _role_obj["confidence"],
+                        "statement": _ARTIFACT_CHANGE_EFFECT.get(_f_atype, "application source (artifact role requires annotation inspection)"),
+                        "classification_method": _f_cls.get("confidence", "low"),
                     },
+                    "evidence_completeness": _impact_entry.get("evidence", {}),
                 }
                 _pr_runtime_changes.append(_entry)
                 # Split committed vs uncommitted — never merged
@@ -2336,17 +2332,10 @@ class TaskContextBuilder:
                 return "service"   # annotation-confirmed — not "core_service" (overclaim)
             return "unclassified"   # no role claim without evidence
 
-        def _score_to_confidence(score: float) -> str:
-            if score >= 0.60:
-                return "high"
-            if score >= 0.40:
-                return "medium"
-            return "low"
-
         def _structured_why(path: str, atype: str, module: str, role: str, risk_areas: list[str], cls_confidence: str = "low") -> str:
             area = _classify_impact_area(path, risk_areas, atype)
             prop = _PROPAGATION_RISK.get(atype, "low") if atype != "source" else "unknown"
-            effect = _CHANGE_EFFECT.get(atype, "may modify application logic (role unconfirmed)")
+            effect = _CHANGE_EFFECT.get(atype, "application source (artifact role requires annotation inspection)")
             parts = [f"artifact_type: {atype}", f"classification_confidence: {cls_confidence}"]
             # Only emit role/area/propagation when there is confirmed evidence (not source/unclassified)
             if role not in ("unclassified",):
@@ -2431,8 +2420,7 @@ class TaskContextBuilder:
             role = _role_in_system(path, atype, in_ep)
             cls_conf = cls.get("confidence", "low")
             why_str = _structured_why(path, atype, module, role, cls["risk_areas"], cls_conf)
-            confidence = _score_to_confidence(score)
-            reason = f"changed since {ref_label} | artifact: {atype} | confidence: {confidence}"
+            reason = f"changed since {ref_label} | artifact: {atype}"
 
             relevant.append(RelevantFile(path=path, role=role, score=round(score, 2), reason=reason, why=why_str))
             why[path] = why_str
@@ -2485,7 +2473,7 @@ class TaskContextBuilder:
             why_str = _structured_why(path, rel_atype, _extract_ddd_domain(path), role, rel_cls["risk_areas"], rel_conf)
             why_str += f" | pulled_by: type-aware expansion from {ctx_type} '{ctx_val}'"
             why_str += f" | triggered_by: {', '.join(triggers[:3])}"
-            reason = f"expansion: {ctx_type} '{ctx_val}' | artifact: {rel_atype} | confidence: {_score_to_confidence(rel_score)}"
+            reason = f"expansion: {ctx_type} '{ctx_val}' | artifact: {rel_atype}"
             related.append((rel_score, path, RelevantFile(
                 path=path, role=role, score=rel_score, reason=reason, why=why_str
             )))
@@ -2595,7 +2583,7 @@ class TaskContextBuilder:
                     _why_str += f" | pulled_by: hop-{_hop_num} import from {Path(_seed_path).name}"
                     _reason = (
                         f"hop-{_hop_num} import-dependent of {Path(_seed_path).name}"
-                        f" ({_seed_atype}) | confidence: {_score_to_confidence(_dep_score)}"
+                        f" ({_seed_atype})"
                     )
                     why[_dep_path] = _why_str
                     # Tests import production code but are not structural dependencies —
@@ -2670,18 +2658,18 @@ class TaskContextBuilder:
                 0.02
             )
             _raw_score = round(min(1.0, _base * 0.50 + _sec_w + _fw + _fanout + _ctw), 3)
+            _caller_count = _downstream_count.get(_path, 0)
             impact_score_per_file[_path] = {
-                "score": _raw_score,
-                "confidence": _score_to_confidence(_raw_score),
-                "score_breakdown": {
-                    "artifact_base": round(_base * 0.50, 3),
-                    "security_weight": _sec_w,
-                    "framework_weight": _fw,
-                    "fanout_weight": round(_fanout, 3),
-                    "change_type_weight": _ctw,
-                },
+                "_rank_score": _raw_score,  # internal ranking only — not a confidence claim
                 "change_types": sorted(_file_ctypes),
                 "diff_severity": _diff_sev,
+                "evidence": {
+                    "has_reverse_edges": _caller_count > 0,
+                    "reverse_edge_count": _caller_count,
+                    "has_route_diff": _diff_sev == "api_change",
+                    "has_security_diff": _diff_sev == "security_change",
+                    "has_wiring_evidence": _atype in {"spring_config", "security"} and _cls.get("confidence") == "high",
+                },
             }
 
         _CT_ORDER = ["security_change", "behavioral_change", "structural_change",
@@ -2714,24 +2702,29 @@ class TaskContextBuilder:
                     changed_subsystems.append(_subsys)
                     _seen_subsys.add(_subsys)
 
-        # behavioral_changes: gated on semantic diff evidence (api_change/security_change),
-        # NOT on artifact type alone. Avoids false behavioral claims for validator/util files.
-        behavioral_changes: list[str] = [
-            f"{Path(_p).name}: {_CHANGE_EFFECT.get(_cls['artifact_type'], 'may modify application logic')}"
-            for _p, _cls in classifications.items()
-            if not _cls["is_noise"]
-            and diff_severities.get(_p, "unknown") in ("api_change", "security_change")
-        ]
+        # behavioral_changes: only emitted when graph evidence exists (import edges found).
+        # Without reverse dependency graph, we cannot make traceable structural claims.
+        # Also gated on semantic diff evidence (api_change/security_change) per file.
+        _has_graph_ev = bool(graph_edges)
+        behavioral_changes: list[str] = (
+            [
+                f"{Path(_p).name}: {_CHANGE_EFFECT.get(_cls['artifact_type'], 'application source (artifact role requires annotation inspection)')} [diff_severity={diff_severities.get(_p)}]"
+                for _p, _cls in classifications.items()
+                if not _cls["is_noise"]
+                and diff_severities.get(_p, "unknown") in ("api_change", "security_change")
+            ]
+            if _has_graph_ev else []
+        )
 
         def _runtime_impact(tc: dict[str, int]) -> list[str]:
             _ri: list[str] = []
             # Only emit claims that are evidence-backed (annotation-confirmed roles)
             if "entrypoint" in tc:
-                _ri.append("Entrypoint-classified file modified — may require full context restart before deploy")
+                _ri.append("Entrypoint-classified file modified — restart required before deploying to production")
             if "spring_config" in tc:
-                _ri.append("Spring config-classified file modified — wired beans may be rewired on restart")
+                _ri.append("Spring @Configuration-classified file modified — bean context rebuild required on restart")
             if "security" in tc:
-                _ri.append("Security-classified file modified — secured endpoints may be affected after restart")
+                _ri.append("Security-classified file modified — inspect authentication and access control wiring")
             if "db_migration" in tc:
                 _ri.append("Database schema migration pending — execute before deploying application")
             # service transactional claim: only if @Service annotation confirmed (not source/unclassified)