sourcecode 1.30.13__tar.gz → 1.30.15__tar.gz

sourcecode-1.30.15/.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.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.13
+Version: 1.30.15
 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.15-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.15
 ```
 
 ---
@@ -353,6 +353,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
 | `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
+| `--format TEXT` | Output format: `json` (default) \| `github-comment` (Markdown PR comment, `review-pr` only). |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
@@ -374,6 +375,9 @@ sourcecode prepare-context delta . --since main
 # Onboard with a ready-to-paste LLM prompt
 sourcecode prepare-context onboard --llm-prompt
 
+# PR analysis as a GitHub Markdown comment (paste directly into PR)
+sourcecode prepare-context review-pr --since main --format github-comment
+
 # List all tasks
 sourcecode prepare-context --task-help
 ```
@@ -444,22 +448,25 @@ sourcecode prepare-context review-pr
       "name": "Order",
       "entry_point": {
         "step": "OrderController.createOrder",
-        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+        "notes": [
+          { "note": "condition: authorization check present (@PreAuthorize / @Secured)",
+            "epistemic_level": "STRUCTURAL SIGNAL" }
+        ]
       },
       "path": [
         {
           "step": "ShippingService.process",
           "notes": [
-            "branch: Spring cache may short-circuit downstream call",
-            "async: runs in separate thread (@Async)"
+            { "note": "branch: Spring cache annotation present — downstream call may be short-circuited",
+              "epistemic_level": "STRUCTURAL SIGNAL" },
+            { "note": "async: @Async annotation present — runs in separate thread",
+              "epistemic_level": "STRUCTURAL SIGNAL" }
           ]
         },
-        {
-          "step": "OrderRepository.save",
-          "notes": []
-        }
+        { "step": "OrderRepository.save", "notes": [] }
       ],
-      "end_state": "DB write"
+      "end_state": "DB write",
+      "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)"
     }
   ]
 }
@@ -474,17 +481,33 @@ sourcecode prepare-context review-pr
 
 **Runtime signals detected per step:**
 
-| Signal | Example code | Note emitted |
-|--------|-------------|--------------|
-| Auth guard | `@PreAuthorize`, `@Secured`, `isAuthenticated()` | `condition: authorization check present` |
-| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` |
-| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` |
-| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache may short-circuit downstream call` |
-| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: result may be absent (Optional)` |
-| Async thread | `@Async`, `CompletableFuture` | `async: runs in separate thread (@Async)` |
-| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` |
-| Kafka | `kafkaTemplate.send()` | `async: Kafka message produced` |
-| RabbitMQ | `rabbitTemplate.send()` | `async: RabbitMQ message sent` |
+| Signal | Example code | Note emitted | Epistemic level |
+|--------|-------------|--------------|-----------------|
+| Auth guard | `@PreAuthorize`, `@Secured` | `condition: authorization check present (@PreAuthorize / @Secured)` | `STRUCTURAL SIGNAL` |
+| Auth context read | `isAuthenticated()`, `SecurityContextHolder` | `condition: reads authentication context` | `STRUCTURAL SIGNAL` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` | `INFERRED (LOW CONFIDENCE)` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` | `STRUCTURAL SIGNAL` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache annotation present — downstream call may be short-circuited` | `STRUCTURAL SIGNAL` |
+| Manual cache | `cache.get()`, `cacheManager.` | `branch: manual cache lookup detected — downstream call may be short-circuited` | `INFERRED (LOW CONFIDENCE)` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: Optional type in use — result may be absent` | `STRUCTURAL SIGNAL` |
+| Async thread | `@Async` | `async: @Async annotation present — runs in separate thread` | `STRUCTURAL SIGNAL` |
+| CompletableFuture | `CompletableFuture`, `.supplyAsync()` | `async: CompletableFuture detected — non-blocking execution` | `STRUCTURAL SIGNAL` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` | `STRUCTURAL SIGNAL` |
+| Kafka | `kafkaTemplate.`, `KafkaProducer` | `async: Kafka producer detected` | `STRUCTURAL SIGNAL` |
+| RabbitMQ | `rabbitTemplate.`, `amqpTemplate.` | `async: RabbitMQ producer detected` | `STRUCTURAL SIGNAL` |
+
+**Epistemic contract:**
+
+Every output field in `review-pr` carries an explicit `epistemic_level`:
+
+| Level | Meaning |
+|-------|---------|
+| `FACT` | Directly observed in diff (file present, config changed) |
+| `STRUCTURAL SIGNAL` | Annotation or type-system evidence in source (`@Service`, `@Transactional`, injection) |
+| `INFERRED (LOW CONFIDENCE)` | Heuristic pattern match — no full structural proof |
+| `OMITTED` | Insufficient evidence — field not emitted |
+
+No field blends certainty levels without labeling. `end_state` (e.g. `"DB write"`) is always accompanied by `end_state_epistemic_level: "INFERRED (LOW CONFIDENCE)"` — it is a keyword-match heuristic, not an AST-verified fact.
 
 **Other `review-pr` output fields:**
 
@@ -492,9 +515,9 @@ sourcecode prepare-context review-pr
 |-------|-------------|
 | `review_hotspots` | Top changed files ranked by impact score |
 | `suggested_review_order` | Security → API → Service → Persistence → Config |
-| `security_impact` | Changed files touching the security surface |
-| `transactional_impact` | Files crossing transaction boundaries |
-| `test_coverage_risk` | Changed source files with no corresponding test |
+| `security_impact` | Changed security-classified files (`epistemic_level: STRUCTURAL SIGNAL`) + risk note (`INFERRED (LOW CONFIDENCE)`) |
+| `transactional_impact` | Changed service/business-logic files with possible transaction boundary effect |
+| `test_coverage_risk` | Changed source files with no corresponding test (`epistemic_level: INFERRED (LOW CONFIDENCE)`) |
 | `affected_modules` | DDD domain modules touched by the change |
 
 ---

{sourcecode-1.30.13 → sourcecode-1.30.15}/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.15-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.15
 ```
 
 ---
@@ -134,6 +134,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
 | `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
+| `--format TEXT` | Output format: `json` (default) \| `github-comment` (Markdown PR comment, `review-pr` only). |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
@@ -155,6 +156,9 @@ sourcecode prepare-context delta . --since main
 # Onboard with a ready-to-paste LLM prompt
 sourcecode prepare-context onboard --llm-prompt
 
+# PR analysis as a GitHub Markdown comment (paste directly into PR)
+sourcecode prepare-context review-pr --since main --format github-comment
+
 # List all tasks
 sourcecode prepare-context --task-help
 ```
@@ -225,22 +229,25 @@ sourcecode prepare-context review-pr
       "name": "Order",
       "entry_point": {
         "step": "OrderController.createOrder",
-        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+        "notes": [
+          { "note": "condition: authorization check present (@PreAuthorize / @Secured)",
+            "epistemic_level": "STRUCTURAL SIGNAL" }
+        ]
       },
       "path": [
         {
           "step": "ShippingService.process",
           "notes": [
-            "branch: Spring cache may short-circuit downstream call",
-            "async: runs in separate thread (@Async)"
+            { "note": "branch: Spring cache annotation present — downstream call may be short-circuited",
+              "epistemic_level": "STRUCTURAL SIGNAL" },
+            { "note": "async: @Async annotation present — runs in separate thread",
+              "epistemic_level": "STRUCTURAL SIGNAL" }
           ]
         },
-        {
-          "step": "OrderRepository.save",
-          "notes": []
-        }
+        { "step": "OrderRepository.save", "notes": [] }
       ],
-      "end_state": "DB write"
+      "end_state": "DB write",
+      "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)"
     }
   ]
 }
@@ -255,17 +262,33 @@ sourcecode prepare-context review-pr
 
 **Runtime signals detected per step:**
 
-| Signal | Example code | Note emitted |
-|--------|-------------|--------------|
-| Auth guard | `@PreAuthorize`, `@Secured`, `isAuthenticated()` | `condition: authorization check present` |
-| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` |
-| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` |
-| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache may short-circuit downstream call` |
-| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: result may be absent (Optional)` |
-| Async thread | `@Async`, `CompletableFuture` | `async: runs in separate thread (@Async)` |
-| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` |
-| Kafka | `kafkaTemplate.send()` | `async: Kafka message produced` |
-| RabbitMQ | `rabbitTemplate.send()` | `async: RabbitMQ message sent` |
+| Signal | Example code | Note emitted | Epistemic level |
+|--------|-------------|--------------|-----------------|
+| Auth guard | `@PreAuthorize`, `@Secured` | `condition: authorization check present (@PreAuthorize / @Secured)` | `STRUCTURAL SIGNAL` |
+| Auth context read | `isAuthenticated()`, `SecurityContextHolder` | `condition: reads authentication context` | `STRUCTURAL SIGNAL` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` | `INFERRED (LOW CONFIDENCE)` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` | `STRUCTURAL SIGNAL` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache annotation present — downstream call may be short-circuited` | `STRUCTURAL SIGNAL` |
+| Manual cache | `cache.get()`, `cacheManager.` | `branch: manual cache lookup detected — downstream call may be short-circuited` | `INFERRED (LOW CONFIDENCE)` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: Optional type in use — result may be absent` | `STRUCTURAL SIGNAL` |
+| Async thread | `@Async` | `async: @Async annotation present — runs in separate thread` | `STRUCTURAL SIGNAL` |
+| CompletableFuture | `CompletableFuture`, `.supplyAsync()` | `async: CompletableFuture detected — non-blocking execution` | `STRUCTURAL SIGNAL` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` | `STRUCTURAL SIGNAL` |
+| Kafka | `kafkaTemplate.`, `KafkaProducer` | `async: Kafka producer detected` | `STRUCTURAL SIGNAL` |
+| RabbitMQ | `rabbitTemplate.`, `amqpTemplate.` | `async: RabbitMQ producer detected` | `STRUCTURAL SIGNAL` |
+
+**Epistemic contract:**
+
+Every output field in `review-pr` carries an explicit `epistemic_level`:
+
+| Level | Meaning |
+|-------|---------|
+| `FACT` | Directly observed in diff (file present, config changed) |
+| `STRUCTURAL SIGNAL` | Annotation or type-system evidence in source (`@Service`, `@Transactional`, injection) |
+| `INFERRED (LOW CONFIDENCE)` | Heuristic pattern match — no full structural proof |
+| `OMITTED` | Insufficient evidence — field not emitted |
+
+No field blends certainty levels without labeling. `end_state` (e.g. `"DB write"`) is always accompanied by `end_state_epistemic_level: "INFERRED (LOW CONFIDENCE)"` — it is a keyword-match heuristic, not an AST-verified fact.
 
 **Other `review-pr` output fields:**
 
@@ -273,9 +296,9 @@ sourcecode prepare-context review-pr
 |-------|-------------|
 | `review_hotspots` | Top changed files ranked by impact score |
 | `suggested_review_order` | Security → API → Service → Persistence → Config |
-| `security_impact` | Changed files touching the security surface |
-| `transactional_impact` | Files crossing transaction boundaries |
-| `test_coverage_risk` | Changed source files with no corresponding test |
+| `security_impact` | Changed security-classified files (`epistemic_level: STRUCTURAL SIGNAL`) + risk note (`INFERRED (LOW CONFIDENCE)`) |
+| `transactional_impact` | Changed service/business-logic files with possible transaction boundary effect |
+| `test_coverage_risk` | Changed source files with no corresponding test (`epistemic_level: INFERRED (LOW CONFIDENCE)`) |
 | `affected_modules` | DDD domain modules touched by the change |
 
 ---

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

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

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

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

{sourcecode-1.30.13 → sourcecode-1.30.15}/src/sourcecode/cli.py

@@ -1622,6 +1622,11 @@ def prepare_context_cmd(
         "--symptom",
         help="(fix-bug) Keyword hint for the bug: boosts matching files and surfaces related code notes.",
     ),
+    format: Optional[str] = typer.Option(
+        None,
+        "--format",
+        help="Output format: json (default) | github-comment (Markdown PR comment for review-pr task)",
+    ),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -1895,7 +1900,12 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
-    _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+    if format == "github-comment" and task == "review-pr":
+        from sourcecode.pr_comment_renderer import render_github_comment
+        _pc_content = render_github_comment(out)
+    else:
+        _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+
     if output_path is not None:
         output_path.write_text(_pc_content, encoding="utf-8")
     else: