sourcecode 1.31.16__tar.gz → 1.31.18__tar.gz

sourcecode-1.31.18/.continue-here.md

@@ -0,0 +1,134 @@
+# Continue Here — atlas-cli sesión 21
+
+**Paused:** 2026-05-24
+**Repo:** `/Users/user/Documents/workspace/atlas-cli`
+**Branch:** master
+**Version:** sourcecode 1.31.17
+
+---
+
+## Objetivo de esta sesión
+
+Continuar corrección de bugs post-auditoría v1.31.16 (adversarial audit contra Keycloak + Broadleaf).
+Sesión 21 atacó los dos P0s. Quedan P1s y P2s.
+
+---
+
+## Trabajo completado esta sesión
+
+### P0-01 — `impact OrderServiceImpl` → 0 callers FIXED ✅
+
+**Root cause:** `_build_reverse_adjacency` descartaba edges `implements` cuando `to` era
+nombre corto no-resuelto (`"OrderService"` en vez de FQN). El `reverse_graph["OrderService"]`
+no tenía clave `"implements"` → scan desde reverse side imposible.
+
+**Fix:** Escanear `graph.edges` forward para `type=implements` FROM matched classes.
+Resolver `to` (short/FQN) contra claves de `reverse_graph` via suffix match.
+Callers de la interfaz se añaden a `direct_callers`. Output incluye `via_interface_resolution`
+y `via_interface_note`.
+
+**Resultado:** `impact OrderServiceImpl` en Broadleaf: 0 callers → **74 callers**, risk LOW → **HIGH**.
+
+### P0-02 — `reverse_graph` unbounded por `--max-nodes`/`--max-edges` FIXED ✅
+
+**Root cause:** `apply_ir_size_limits` sólo acotaba `graph.nodes`/`graph.edges`.
+`reverse_graph` emitía 2685 claves (~3MB) aunque se pidieran 200 nodos.
+
+**Fix:** Cuando `max_nodes` activo: restringir `reverse_graph` a `kept_fqns` + cap inner
+caller lists a `max(20, max_nodes//4)`. Cuando sólo `max_edges`: cap a `max_edges` claves
+por in-degree. Añade `reverse_graph_note` cuando trimmed.
+
+**Resultado:** `--max-nodes 200 --max-edges 500`: 3.85MB → **939KB** (76% reducción).
+
+### Commit esta sesión
+
+```
+e5fba19  fix(ir): resolve Spring DI interface bridging and bound reverse_graph
+```
+
+---
+
+## Estado archivos sin commitear
+
+```
+?? AUDIT_REAL_REPOS.md          — auditoría 22 secciones (de sesión 20, no tocar)
+?? docs/PRODUCT_TIERS.md        — de sesión anterior (no tocar esta sesión)
+```
+
+Commitear estos docs antes de continuar con fixes:
+```bash
+git add AUDIT_REAL_REPOS.md docs/PRODUCT_TIERS.md
+git commit -m "docs(audit): adversarial audit v1.31.16 — real benchmarks, P0/P1/P2 findings"
+```
+
+---
+
+## Bugs pendientes por ROI
+
+### P1 — Altos
+
+| # | Bug | Archivo | Tiempo est. |
+|---|-----|---------|-------------|
+| **P1-01** | Risk score inconsistente para 0-caller impls: `OrderServiceImpl`→low vs `OrderDaoImpl`→high (mismo 0 callers, distinta heurística). POST P0-01 fix: verificar si aún aplica o si interface bridging ya lo resuelve. | `repository_ir.py` → `compute_blast_radius` | 30 min |
+| **P1-02** | `project_summary` = primera línea del README (license/marketing). Debe generarse de código: "N-module Spring Boot — M classes, K endpoints, J txn boundaries" | `serializer.py` o `summarizer.py` | 1h |
+| **P1-03** | `fix-bug` devuelve 426 archivos para NPE genérico (14% repo, sin `score` field) | `prepare_context.py` → `fix_bug` | 30 min |
+| **P1-04** | `indirect_callers:0` para KeycloakSession (1992 direct callers) — BFS para en nivel 1 por hub guard | `repository_ir.py` → `compute_blast_radius` hub guard logic | 45 min |
+| **P1-05** | `fix-bug` 23s cold en Keycloak | profiling needed | ~1h |
+
+### P2 — Medios (batch)
+
+- `bounded_contexts: ["dto","file"]` Broadleaf — WRONG. Fix: usar Maven module names
+- `role: unknown` para todos `high_coupling_nodes` en modernize — nunca clasifica annotation/interface/entity
+- `no_security_signal: 100%` en ambos repos — filter-based security nunca detectado
+- JAX-RS sub-resource paths no compuestos con parent `@Path`
+- `hotspot_candidates: []` siempre — git churn ignorado
+- `--format`/`--no-cache` ausentes en `impact`, `endpoints`, `fix-bug`, `onboard`, `modernize`, `review-pr`
+- Architecture confidence diferente entre `--compact` y `--agent` mismo repo
+
+---
+
+## Primera acción al retomar
+
+```bash
+cd /Users/user/Documents/workspace/atlas-cli
+
+# 1. Commitear docs pendientes
+git add AUDIT_REAL_REPOS.md docs/PRODUCT_TIERS.md
+git commit -m "docs(audit): adversarial audit v1.31.16 — Keycloak + Broadleaf findings"
+
+# 2. Verificar si P1-01 aún existe post-fix P0-01:
+sourcecode impact OrderDaoImpl ~/Documents/workspace/BroadleafCommerce 2>&1 | python3 -m json.tool | grep -E 'risk_level|confidence_level|direct_callers|via_interface'
+# Si risk_level sigue siendo inconsistente → fix P1-01
+# Si interface bridging ya lo resuelve → skip a P1-02
+
+# 3. Si P1-01 persiste:
+# En compute_blast_radius: cuando direct_callers=0 Y no hay interface bridging Y
+# clase es @Service/@Repository impl → bajar confidence, añadir gap en explanation
+```
+
+---
+
+## Archivos clave del codebase
+
+```
+src/sourcecode/
+  repository_ir.py    — impact analysis, blast radius, interface bridging (P0-01/02 fixeados aquí)
+  prepare_context.py  — fix-bug, onboard, review-pr output (P1-03 aquí)
+  serializer.py       — compact/agent output, project_summary (P1-02 aquí)
+  summarizer.py       — ProjectSummarizer (P1-02 posiblemente aquí)
+  cli.py              — top-level commands, cache logic
+tests/
+  test_enterprise_benchmarks.py
+```
+
+---
+
+## Contexto de versiones
+
+- v1.31.16: bugs auditados en sesión 20
+- v1.31.17: versión actual (bumpeada en 0cf28b1 por el usuario)
+- Fixes P0-01/P0-02: commit e5fba19 (sesión 21)
+
+---
+
+*Pausado 2026-05-24 — gsd:pause-work (sesión 21)*

sourcecode-1.31.18/AUDIT_REAL_REPOS.md

@@ -0,0 +1,539 @@
+# sourcecode — P1.5 Credibility Audit
+**Adversarial audit against real enterprise Java repos. No synthetic fixtures.**
+
+Version audited: 1.31.17
+Date: 2026-05-24  
+Repos: `~/Documents/workspace/keycloak` (7885 Java files, 18K+ commits), `~/Documents/workspace/BroadleafCommerce` (2985 Java files, 18K+ commits)
+
+---
+
+## 1. Executive Summary
+
+`sourcecode` delivers real, non-trivial value for Java/Spring enterprise codebases. The compact/agent scan, cache system, event flow detection, and transactional boundary extraction are genuinely useful. The `review-pr --format github-comment` output is above MVP and commercially differentiated.
+
+**But the core `impact` command has a P0 correctness bug** that fundamentally undermines the product's main claim: for implementation classes (the natural query for a developer), it returns 0 callers with `confidence_level: high`. This is systematically wrong — the worst possible failure mode.
+
+**Verdict:** `trust with caveats` — solid foundation, monetizable with specific fixes. Not yet safe to pitch as "AI-ready change intelligence" without fixing P0 and P1 issues.
+
+---
+
+## 2. Methodology
+
+- `sourcecode --help` + all sub-command `--help` reviewed
+- `sourcecode --compact`, `--agent`, `--format yaml` on both repos (cold + cached)
+- `sourcecode endpoints` on both repos with path quality analysis
+- `sourcecode impact` on: impl classes, interface classes, nonexistent targets, high-fan-in annotation classes
+- `sourcecode onboard`, `fix-bug`, `modernize`, `review-pr` on both repos
+- `sourcecode repo-ir --summary-only` and `--max-nodes 200 --max-edges 500`
+- `sourcecode prepare-context` vs standalone aliases (diff comparison)
+- Cache behavior: cold→warm timing, determinism (same output across runs)
+- Error handling: invalid refs, missing targets, wrong flag combos
+- Flag consistency audit across all commands
+
+---
+
+## 3. Repo-by-Repo Findings
+
+### Keycloak (7885 Java files — major IAM server, Quarkus/Jakarta EE)
+
+**What worked:**
+- Stack: correctly detected Quarkus + Jakarta EE + Vert.x + Node.js secondary
+- Bootstrap entry points: correct (KeycloakMain, QuarkusKeycloakApplication, Main)
+- 693 JAX-RS endpoints extracted from annotations
+- Dependency list accurate (Jackson, WebAuthn4j, OpenTelemetry, FIPS providers, etc.)
+- javax-to-jakarta migration risk flag correctly raised
+- Cold scan `--compact`: 9s. Cached: 0.27s (~33x speedup)
+- `fix-bug --symptom "OIDC token refresh fails after realm update"`: correct files surfaced (OIDCLoginProtocolService, RefreshTokenGrantType, RefreshTokenGrantTypeFactory). Budget trimmed 204KB → 15KB — safety net works.
+- Spring profile `rhbk` (Red Hat's Keycloak fork) detected from env_vars
+
+**What failed:**
+- `project_type: "fullstack"` — Keycloak is an IAM **server product**, not a generic fullstack app
+- `project_summary` copied from README ("Add authentication to applications...") — describes what Keycloak does for *users*, not what the *codebase does architecturally*
+- `bounded_contexts: ["keycloak"]` — too generic; Keycloak has clear subsystem boundaries (oidc, saml, federation, authz, admin, operator)
+- `entry_points.security` mixes SPI implementations (CredentialProvider, AuthenticatorFactory) with actual security filters — different concerns in same bucket
+- `DefaultKeycloakSession` impact: **2 direct callers** (should be hundreds — injected via `KeycloakSession` interface everywhere). P0 bug.
+- `KeycloakSession` interface impact: 1992 direct callers found but `indirect_callers: 0` — BFS exhausts at level 1 on very large fan-out
+- Short JAX-RS paths (`/{id}`, `/sessions`) — sub-resource paths not composed with parent `@Path`
+- `fix-bug` cold: 23s — slowest workflow, too slow for CI integration
+- `no_security_signal: 693` for all endpoints — Keycloak uses JAX-RS filter security; metric provides zero signal
+
+### BroadleafCommerce (2985 Java files — e-commerce framework, Spring Boot)
+
+**What worked:**
+- Stack: correctly detected Spring Boot + Spring MVC + Spring Security + Spring LDAP + Spring AOP
+- Security filter chain detected (SecurityFilter, CsrfFilter, SecurityBasedIgnoreFilter)
+- `transactional_boundaries`: 29 classes correctly identified (OrderServiceImpl, OrderDaoImpl, OfferServiceImpl, etc.)
+- Event flow: listeners, publishers, event types correctly extracted (CustomerPersistedEvent, OrderPersistedEvent, TransactionLifecycleEvent)
+- Cache: 2.9s cold → 0.2s cached (~13x speedup)
+- Dependency extraction with version info and risk flags correct
+- review-pr: `HEAD~3` diff correctly identified 3 source changes + 13 build manifest changes
+- review-pr invalid ref: structured JSON error with available branch list
+
+**What failed:**
+- `project_type: "api"` — BroadleafCommerce is an e-commerce **framework**, not a generic REST API
+- `project_summary` lifted from README license notice ("Available to companies with under $5M in revenue...") — license blurb, not architecture summary
+- `bounded_contexts: ["dto", "file"]` — WRONG. Real bounded contexts: Order, Catalog, Customer, CMS, Offer/Pricing
+- `OrderServiceImpl` impact: **0 callers, risk_level: low, confidence_level: high** — WRONG. Most central class in order system; 43+ dependent files
+- `OrderDaoImpl` impact: **0 callers, risk_level: high** — same 0-caller root cause, different risk level. Inconsistent behavior from same bug.
+- 58 endpoint paths with colon notation (`/product:product`, `/bundle:bundle/{id}`) — unresolved constant expressions in annotations
+- 20 endpoint paths that are FQN class names (`/org.broadleafcommerce.core.search.domain.FieldImpl`) — Broadleaf admin dynamic routing, not real REST paths
+- `hotspot_candidates: []` despite 18K+ commits — git churn not used in hotspot analysis
+- `cross_module_tangles: []` — 8 subsystems with known coupling, algorithm detects nothing
+- `no_security_signal: 130` — Broadleaf uses XML-based security and custom AdminSecurityFilter; annotation detection returns nothing
+- `entry_points.controllers: {methods: 21}` vs `endpoints` finding 130 — unexplained discrepancy
+
+---
+
+## 4. Core Engine Correctness
+
+### Endpoint Extraction
+
+| Metric | Keycloak | Broadleaf |
+|--------|----------|-----------|
+| Endpoints found | 693 | 130 |
+| Controller/handler present | ✓ | ✓ |
+| Paths fully composed (parent + child) | Partial | Partial |
+| Paths with annotation constant issues | ~0 | 58 (colons) |
+| FQN class name paths (dynamic routing) | 0 | 20 |
+| Security signal useful | ✗ (filter-based) | ✗ (XML+filter) |
+
+**JAX-RS sub-resource paths:** Methods with `@GET/@POST` inside a `@Path`-annotated class extract only the method-level path. Parent path not composed → incomplete, ambiguous paths.
+
+**Spring MVC constant expressions:** `@RequestMapping("/" + CONST_A + ":" + CONST_B)` → extracted as `/product:product`. Tool resolves string constants but the resulting path is unintelligible as a REST URL without domain knowledge.
+
+### Impact Analysis — THE KEY FINDING
+
+**P0 Bug: Spring DI interface-injection blindness**
+
+When `OrderServiceImpl implements OrderService` and all callers inject `@Autowired OrderService orderService`:
+
+```
+sourcecode impact OrderServiceImpl /BroadleafCommerce
+→ direct_callers: 0, risk_level: low, confidence_level: HIGH
+
+sourcecode impact OrderService /BroadleafCommerce  
+→ direct_callers: 30, indirect_callers: 50, endpoints_affected: 11, risk_level: high
+```
+
+This pattern is universal in Spring and Java DI: callers inject the interface, not the impl. Querying impl classes returns wrong answers. The tool documents this ("Target interfaces, not implementations"), but:
+
+1. `confidence_level: high` for the wrong 0-caller answer is the worst possible failure mode — a developer gets high-confidence garbage
+2. The natural query is the class name you're editing, which is the impl
+3. The tool should detect `@Service`/`@Repository` impls and warn/auto-redirect
+
+**Risk score inconsistency from same root cause:**
+- `OrderServiceImpl`: 0 callers → risk_level: **low** (no heuristic applies)
+- `OrderDaoImpl`: 0 callers → risk_level: **high** (persistence path heuristic: "15 persistence paths in blast cone")
+
+Both return 0 callers for the same Spring DI reason. They get different risk levels based on which heuristics fire. A developer comparing both would incorrectly conclude `OrderDaoImpl` is riskier.
+
+**What works in impact:**
+- Interface targets: accurate (OrderService: 30 direct, 50 indirect, 11 endpoints — matches grep-based verification of ~43 dependent files)
+- Annotation classes: accurate (AdminPresentationClass: 278 found vs 285 actual in_degree — 2.4% gap)
+- Nonexistent target: clean `{resolution: "not_found"}` response
+- High fan-in interfaces: KeycloakSession 1992 direct callers correctly found
+
+### Confidence Scoring Inconsistency
+
+compact: `sections.architecture = "low"`, factor: `"architecture.confidence=low → overall capped at medium"`  
+agent: `sections.architecture = "medium"`, factor: `"architecture.confidence=medium → downgraded"`
+
+Same repo (Broadleaf), different confidence levels between compact and agent modes. Schema inconsistency.
+
+---
+
+## 5. Performance / Scale
+
+| Command | Keycloak (7885 files) | Broadleaf (2985 files) |
+|---------|-----------------------|------------------------|
+| `--compact` cold | 9.0s | 2.9s |
+| `--compact` cached | 0.27s | 0.20s |
+| `--agent` cold | 17s | 7.3s |
+| `impact interface` | ~12s | 5.9s |
+| `fix-bug` cold | **23s** | 8.8s |
+| `onboard` cold | n/a | 6.7s |
+| `modernize` cold | n/a | 5.5s |
+| `repo-ir --summary-only` | 12s | 5.4s |
+| Cache speedup | ~33x | ~13x |
+
+**`repo-ir --max-nodes 200 --max-edges 500`:** Output = **3,948,466 bytes / 987K tokens**. The flags only bound `graph.nodes/edges`. `reverse_graph` (3MB for 2685 hubs) is entirely unbounded.
+
+**Token sizes (measured):**
+
+| Output mode | Broadleaf | Keycloak |
+|-------------|-----------|----------|
+| `--compact` | 2,856 | 4,031 |
+| `--agent` | 4,769 | 5,499 |
+| `onboard` | 2,564 | n/a |
+| `fix-bug` (trimmed) | 27,653 | 4,648 |
+| `fix-bug` (raw before trim) | ~24,500 | ~51,000 |
+| `repo-ir --summary-only` | 19,756 | 16,885 |
+| `repo-ir --max-nodes 200` | **987,116** | n/a |
+
+The budget trimming in fix-bug is a real safety net (204KB → 15KB for Keycloak). The concern is the 204KB raw size — if the budget check ever fails, LLM context floods.
+
+---
+
+## 6. Workflow Audit
+
+### `onboard` — MVP correct
+**Signal:** 26 relevant files, entry points, transactional boundaries, gaps.  
+**Issues:** `project_summary` from README blurb. `relevant_files` has no `score` field. Gaps section too generic.  
+**Rating:** MVP correct — useful, not polished.
+
+### `impact` — below MVP for impl classes
+**Signal:** Correct for interfaces. Wrong with high confidence for impls.  
+**Issues:** P0 bug. See Section 4. The main claim breaks for 95% of developer queries.  
+**Rating:** Below MVP for primary use case.
+
+### `fix-bug` — above MVP for specific symptoms
+**Signal:** Good file ranking for keyword-rich symptoms. Budget trimming works.  
+**Issues:** 426 files returned for generic NPE symptom in 2985-file repo. No score field in relevant_files. 23s cold on Keycloak.  
+**Rating:** Above MVP for specific symptoms, MVP for generic ones.
+
+### `review-pr` — above MVP
+**Signal:** Excellent `github-comment` format with epistemic labels. Correctly separates build manifest from source changes.  
+**Issues:** `classification_confidence: low` for simple 3-file validator PRs. Validator role not detected.  
+**Rating:** Above MVP. The github-comment format is the strongest differentiator in the product.
+
+### `modernize` — MVP only
+**Signal:** `high_coupling_nodes` correctly identifies high-fan-in classes. Dead zone candidates plausible.  
+**Issues:** `hotspot_candidates: []` always. `cross_module_tangles: []`. `role: unknown` for all nodes.  
+**Rating:** MVP only.
+
+### `repo-ir --summary-only` — MVP correct
+**Signal:** Spring events, route surface, impact.ranked_nodes all present.  
+**Issues:** 19K tokens even in summary mode. `reverse_graph_note: "showing 10/2685 hubs"` — correctly bounded in summary mode.  
+**Rating:** MVP correct for `--summary-only`. Use without it only with `--files`.
+
+### `prepare-context` vs top-level aliases
+Output is **byte-for-byte identical** to `sourcecode onboard`, `sourcecode fix-bug`, etc. (verified by diff). Documented in README but creates confusing dual API surface.
+
+---
+
+## 7. CLI / UX Audit
+
+**Flag inconsistency:**
+- `--format yaml`: main command ✓, endpoints ✓, repo-ir ✓. `impact` ✗, `onboard` ✗, `fix-bug` ✗, `review-pr` ✗, `modernize` ✗
+- `--no-cache`: main command ✓. `endpoints` ✗, `impact` ✗, task commands ✗
+
+**`--deep` flag:** Referenced in output (`"Use --deep for up to 80 files"`) but absent from `--help` and README. Hidden feature.
+
+**Error messages:**
+- Nonexistent target: clean JSON `{resolution: "not_found"}` ✓
+- Invalid git ref: structured JSON with available branch hints ✓
+- `--compact --full` mutual exclusion: clear plain text ✓
+- `--format yaml` on `impact`: generic Click error ✗
+
+**Schema stability issues:**
+- `truncated: None` (absent) vs `truncated: false` (explicit) — prefer always explicit boolean
+- `impact.direct_callers` list truncated to 30 without adjacent count — actual count in `stats.direct_caller_count` and `explanation` text only
+- Architecture confidence different between `--compact` and `--agent` modes for same repo
+
+**--help token claim:**
+- `--compact --help`: "typically 1000–3000 tokens"
+- README quickstart: "typically 2000–4000 tokens"
+- Measured: 2856–4031 for these repos
+
+---
+
+## 8. LLM / Agent Readiness
+
+**Safe to inject into LLM context:**
+- `--compact`: 2856–4031 tokens ✓
+- `--agent`: 4769–5499 tokens ✓
+- `onboard`: ~2564 tokens ✓
+- `fix-bug` (Keycloak, after trim): 4648 tokens ✓
+- `review-pr`: 2720 tokens ✓
+
+**NOT safe without `--summary-only` or `--files`:**
+- `repo-ir`: can exceed 987K tokens
+- `fix-bug` raw before budget: 51K tokens (Keycloak), 24K (Broadleaf)
+
+**Agent signal quality:**
+- `confidence_summary.factors` with machine-readable explanations: ✓
+- `analysis_gaps` with `area` + `reason` + `impact`: ✓
+- `ci_decision` in `review-pr`: ✓
+- `suggested_review_order` in `review-pr`: ✓
+- `relevant_files` with score: ✗ (missing — agent can't weight files)
+- Determinism: ✓ (same output across repeated runs)
+- Structured failures (JSON errors, not stack traces): ✓
+
+---
+
+## 9. Bugs & Inconsistencies
+
+### P0 — Critical Correctness
+
+**BUG-P0-01: `impact` returns 0 callers for Spring impl classes with high confidence**
+- Command: `sourcecode impact OrderServiceImpl /BroadleafCommerce`
+- Observed: `direct_callers: [], risk_level: "low", confidence_level: "high"`
+- Expected: 30+ direct callers via interface, risk_level: high
+- Root cause: Graph traces direct import edges only. When callers inject via `OrderService` interface, `OrderServiceImpl` has zero incoming edges.
+- Risk: High-confidence wrong answer before risky refactors = missed blast radius = production incidents.
+- Fix: Detect `@Service`/`@Component`/`@Repository` impls with 0 callers and their interfaces. Auto-merge interface impact OR emit warning: `"0 callers found — callers of interface OrderService: 30. Run: sourcecode impact OrderService"`
+
+**BUG-P0-02: `repo-ir --max-nodes N --max-edges N` does not bound output**
+- Command: `sourcecode repo-ir /BroadleafCommerce --max-nodes 200 --max-edges 500`
+- Observed: 3,948,466 bytes / 987K tokens
+- Root cause: Flags only limit `graph.nodes/edges`. `reverse_graph` (3,092KB for 2685 hubs × 20 callers) is unaffected.
+- Risk: LLM context overflow. Users expecting size control get none.
+- Fix: Apply limits to `reverse_graph` hubs as well, OR rename flags to `--max-graph-nodes`/`--max-graph-edges` and document the gap clearly.
+
+### P1 — High Severity
+
+**BUG-P1-01: Risk score inconsistency for same 0-caller root cause**
+- `OrderServiceImpl`: 0 callers → risk_level: **low** (no heuristic)
+- `OrderDaoImpl`: 0 callers → risk_level: **high** (persistence path heuristic)
+- Both have 0 callers for identical Spring DI reason. Different risk levels from different heuristics.
+- Fix: When `direct_callers = 0` and class is a Spring impl, suppress confidence and add a gap annotation.
+
+**BUG-P1-02: `project_summary` copies README license/marketing text**
+- Broadleaf: `"Available to companies with under $5M in revenue — it is not an Apache 2 open source product"`
+- Keycloak: `"Add authentication to applications and secure services with minimum effort"`
+- These are first lines of READMEs — license/marketing, not architecture.
+- Fix: Generate from code structure: `"N-module Spring Boot framework — M Java classes, K REST endpoints, J transactional boundaries"`.
+
+**BUG-P1-03: `fix-bug` returns 426 relevant files for generic NPE symptom in 2985-file repo**
+- 14% of all Java files flagged as relevant
+- No `score` field — agent can't prioritize
+- Fix: Cap at 20 files when symptom is generic (low keyword specificity). Add `score` field.
+
+**BUG-P1-04: `indirect_callers: 0` for KeycloakSession with 1992 direct callers**
+- BFS appears to exhaust budget at level 1, never computes level 2+ transitive callers
+- Fix: Sample BFS on very large fan-out targets, or document behavior explicitly.
+
+**BUG-P1-05: Keycloak `fix-bug` 23s cold**
+- Broadleaf: 8.8s. Keycloak 7885 files: 23s.
+- Marginal for interactive use, problematic for CI gates.
+- Fix: Profile hotpath. Consider `--fast` flag for fix-bug (exists in prepare-context but not fix-bug).
+
+### P2 — Medium Severity
+
+**BUG-P2-01: `bounded_contexts` wrong for both repos**
+- Keycloak: `["keycloak"]` — one name for a multi-subsystem IAM server
+- Broadleaf: `["dto", "file"]` — utility packages, not domain contexts
+- Fix: Use Maven module names as primary signal for bounded context detection.
+
+**BUG-P2-02: `role: unknown` for all `modernize.high_coupling_nodes`**
+- All 20 nodes including annotation types, interfaces, domain entities have `role: "unknown"`
+- Fix: Detect `@interface` (annotation), `interface`, `@Entity`, `@Service`, etc. from source.
+
+**BUG-P2-03: `no_security_signal` always 100% for filter-based security**
+- Both repos: all endpoints flagged despite being secured (via filter/XML config)
+- Metric provides zero signal for the most common enterprise Java security pattern
+- Fix: Detect `WebSecurityConfigurerAdapter`, `SecurityConfig`, custom `Filter` impls. When present, change metric to `security_model: "filter_based"`.
+
+**BUG-P2-04: JAX-RS sub-resource paths not composed with parent `@Path`**
+- Keycloak: `GET /{id}`, `/sessions` instead of `/admin/realms/{realm}/clients/{id}`
+- Fix: Compose method `@Path` with class-level `@Path` during extraction.
+
+**BUG-P2-05: Broadleaf admin framework paths mixed with REST endpoints**
+- 20 paths with FQN class names (`/org.broadleafcommerce.core.search.domain.FieldImpl`)
+- 58 paths with colon notation from constant concatenation (`/product:product`)
+- Fix: Flag paths containing dots or colons (outside `{var}` segments) as `routing_type: "admin_framework"`.
+
+**BUG-P2-06: Architecture confidence inconsistent between `--compact` and `--agent`**
+- Same repo, different architecture confidence (low in compact, medium in agent)
+- Fix: Unify architecture confidence calculation regardless of output mode.
+
+**BUG-P2-07: `entry_points.controllers.methods: 21` vs `endpoints` finding 130**
+- Unexplained discrepancy for same repo
+- Fix: Align or explain the difference.
+
+**BUG-P2-08: `--format` and `--no-cache` inconsistently available**
+- `--format`: works on main/endpoints/repo-ir, fails on impact/onboard/fix-bug/modernize
+- `--no-cache`: works on main, fails on all subcommands
+- Fix: Add consistently to all commands, or document the restriction.
+
+### Cosmetic
+
+- Code notes URLs truncated: `"s.webkit.org/..."` instead of `"https://bugs.webkit.org/..."`
+- `truncated: None` (absent key) vs `truncated: false` (explicit boolean) — prefer always explicit
+- `run_id` in task outputs — purpose undocumented
+- `direct_callers` list truncated to 30 without adjacent count field
+- `--compact --help` says "1000–3000 tokens", README says "2000–4000 tokens" — inconsistent
+- `--deep` flag referenced in output but absent from `--help` and README
+
+---
+
+## 10. Good / Bad / Ugly
+
+### The Good
+- Cache system: 13–33x speedup, content-hash keyed, deterministic
+- Spring event flow detection: listeners + publishers + event types
+- Transactional boundary detection: 29 Broadleaf classes correctly identified
+- javax-to-jakarta migration risk flags
+- `review-pr --format github-comment`: epistemic labels (FACT / STRUCTURAL SIGNAL / INFERRED / OMITTED)
+- Structured error responses (JSON errors with recovery hints)
+- fix-bug budget trimming (204KB → 15KB safety net works)
+- Interface impact accuracy (~97.6% of actual in_degree for annotation classes)
+- Deterministic: same output across repeated runs
+
+### The Bad
+- `impact` on impl classes: 0 callers with high confidence — the core value prop fails for natural queries
+- `project_summary` from README blurb — zero architectural intelligence
+- `bounded_contexts` detection wrong for both repos
+- `hotspot_candidates: []` always for annotation-heavy repos
+- `repo-ir` size explosion with `--max-nodes/edges`
+
+### The Ugly
+- Risk score diverges for same bug: `OrderServiceImpl` → low, `OrderDaoImpl` → high. Same root cause, opposite conclusions.
+- `indirect_callers: 0` for KeycloakSession (1992 direct callers). BFS stops at level 1. An LLM given this would underestimate transitive impact.
+- 24% of Broadleaf endpoints are non-REST paths mixed into the list without differentiation.
+
+---
+
+## 11. What Works Above MVP
+
+1. Cache system (13–33x speedup, content-hash keyed)
+2. Spring event flow detection
+3. Transactional boundary detection with class names
+4. javax-to-jakarta migration risk flag
+5. `review-pr --format github-comment` with epistemic labels
+6. Structured JSON error responses
+7. fix-bug budget trimming
+8. Interface impact accuracy (~97.6% for annotation classes)
+9. Deterministic, cacheable outputs
+10. review-pr: build manifest vs source file differentiation
+
+---
+
+## 12. What Is MVP Only
+
+1. Stack detection
+2. Entry point detection (bootstrap files)
+3. compact/agent onboarding
+4. YAML output format
+5. Spring MVC endpoint extraction
+6. Dependency extraction with versions
+7. Code notes extraction (TODO/BUG/FIXME)
+8. review-pr JSON format
+9. onboard workflow
+
+---
+
+## 13. What Is Below MVP
+
+1. `impact` on impl classes (P0)
+2. `repo-ir` size control with `--max-nodes/edges` (P0)
+3. `hotspot_candidates` — always empty in annotation-heavy repos
+4. `bounded_contexts` detection — wrong for both repos
+5. JAX-RS sub-resource path composition
+6. `no_security_signal` for filter-based security projects
+7. `project_summary` generation for enterprise codebases
+
+---
+
+## 14. Market Differentiation
+
+### What pain does `sourcecode` actually solve?
+
+**Blast radius blindness in Java monoliths.** Senior engineers spend 30-60 minutes per PR doing manual blast radius assessment. `sourcecode impact` collapses this to seconds — when it works (interface targets): 30 direct callers, 50 indirect, 11 endpoints in 6 seconds.
+
+**New engineer/agent ramp-up in 7885-file codebases.** `sourcecode onboard` produces a bounded, structured context bundle — the right answer in seconds, not hours of grepping.
+
+**LLM context preparation for Java repos.** AI agents working on Java monoliths fail from context overflow. `sourcecode` pre-selects highest-signal files and produces bounded JSON. The fix-bug 204KB → 15KB trim is a concrete example.
+
+### What alternatives don't provide
+
+| Alternative | What it misses |
+|-------------|---------------|
+| grep / find | No structure, no graph, no ranking |
+| IDE navigation | Interactive only; not scriptable; not AI-ready |
+| LSP (Java Language Server) | Requires JVM; slow startup; no bounded JSON output |
+| SonarQube | Static quality analysis, not change intelligence |
+| GitHub code search | No impact graph; no transactional awareness |
+| MCP wrappers | Dumps raw files; no pre-selection; no bounded signal |
+
+`sourcecode` uniquely combines: static Java graph analysis + bounded AI-ready output + change impact + transactional awareness. No direct competitor produces this combination in sub-10-second cold scans.
+
+**The gap:** The P0 impl-class impact bug makes the strongest claim ("what breaks if I change X?") unreliable for the majority of queries in Spring codebases. Fix this and the differentiation holds.
+
+---
+
+## 15. Concrete Corrections Recommended
+
+**Priority 1 (fix before enterprise pitch):**
+1. `impact`: Detect `@Service`/`@Repository` impl with 0 callers → auto-run on interfaces OR warn with: `"0 callers found — callers of interface OrderService: 30. Consider: sourcecode impact OrderService"`
+2. `repo-ir`: Apply `--max-nodes/edges` limits to `reverse_graph` hubs as well, OR document clearly.
+3. `project_summary`: Generate from code structure, not README. Template: `"[N-module Spring Boot/Quarkus] — [M] Java classes, [K] REST endpoints, [J] transactional boundaries."`
+
+**Priority 2 (improve credibility):**
+4. When `direct_callers = 0` and class is Spring impl: lower `confidence_level` to medium and add gap: `"impl class — consider targeting interface for full caller graph."`
+5. `bounded_contexts`: Use Maven module names as primary signal.
+6. `no_security_signal`: Detect filter-based security. Change to `security_model: "filter_based"` + note.
+7. `modernize.hotspot_candidates`: Use git churn (`git log --follow --name-only`) combined with coupling degree.
+8. `modernize.high_coupling_nodes.role`: Classify annotation types, interfaces, entities — never return `"unknown"`.
+
+**Priority 3 (polish):**
+9. Add `score` field to `relevant_files` in all task outputs.
+10. Add `direct_callers_count` alongside `direct_callers` list.
+11. Add `--format`/`--no-cache` consistently to all commands.
+12. Fix URL truncation in code_notes.
+13. Fix `truncated: None` → always explicit `truncated: false`.
+14. Add `--deep` to `--help` output.
+15. Unify architecture confidence between `--compact` and `--agent`.
+16. Align `entry_points.controllers.methods` with `sourcecode endpoints` count.
+17. Fix `--compact --help` vs README token count inconsistency (claim: 1000-3000, measured: 2856-4031).
+
+---
+
+## 16. High-Leverage Feature Opportunities
+
+**Interface → impl resolution** (extends the P0 fix):  
+Auto-detect interface when user targets impl. Present: "Direct callers of impl: 0. Via interface: 30. Using interface results." Makes impact correct by default.
+
+**Git churn coupling (hotspot 2.0):**  
+Combine temporal coupling (files changed together in same commit), static import coupling, and fan-in degree. "Change risk index" per file. Monetizable as continuous CI/CD signal.
+
+**PR risk score:**  
+Single `risk_score: 0–100` from: blast radius of changed classes + test coverage + transactional boundaries touched + security surface changes. CI gate in one field.
+
+**Dead code confidence:**  
+Combine git recency + zero import edges + no test pair → confidence-scored dead code. Flat list vs scored list — the latter is actionable.
+
+**Security surface change detection:**  
+Flag when a PR modifies a class in the security filter chain or a direct caller of security-annotated endpoints.
+
+**Transactional lineage:**  
+For each `@Transactional` class, show which JPA entities and queries it coordinates. Critical for data corruption bug triage.
+
+---
+
+## 17. Final Verdict
+
+| Dimension | Rating |
+|-----------|--------|
+| Core correctness (interface targets) | ✓ Strong |
+| Core correctness (impl targets) | ✗ P0 bug |
+| Performance | ✓ Acceptable |
+| Boundedness (compact/agent) | ✓ Solid |
+| Boundedness (repo-ir) | ✗ Broken |
+| LLM readiness | ✓ With caveats |
+| CLI surface coherence | ~ Mixed |
+| Market differentiation | ✓ Real |
+| Documentation accuracy | ~ Mostly accurate |
+| Verdict | **trust with caveats** |
+
+**Safe to use for:**
+- Onboarding new engineers/agents (`onboard`)
+- PR review context (`review-pr`)
+- Bug triage with specific symptoms (`fix-bug --symptom "..."`)
+- Interface impact analysis
+
+**Not safe without knowing limits:**
+- `impact ClassName` when ClassName is a Spring impl
+- `repo-ir` without `--summary-only`
+- `no_security_signal` as a real security indicator
+- `hotspot_candidates` as a completeness signal
+
+**Monetizable today:**
+- `review-pr --format github-comment` as a GitHub Action
+- `impact` on interface classes as a pre-commit/pre-PR tool
+- `fix-bug` for symptom-driven triage in support scenarios
+- `onboard` as first-prompt injection for AI coding agents
+
+**Not yet monetizable without fix:**
+- "AI-ready change intelligence" claim needs P0 fix
+- "Know what breaks before you touch it" needs reliable impl-class impact