From 95d984735461ea064de9662a877838b012d9f2f6 Mon Sep 17 00:00:00 2001
From: "Dhanji R. Prasanna" <d@wideplay.com>
Date: Mon, 2 Feb 2026 17:20:15 +1100
Subject: [PATCH] Update dependency analysis artifacts with detailed evidence

- hotspots.md: Added specific dependent file lists for each hotspot
- hotspots.md: Added cross-crate coupling points table
- hotspots.md: Added crate-level coupling scores
- limitations.md: Expanded coverage of unobservable patterns
- limitations.md: Added confidence levels for inferences
- limitations.md: Added extraction method details table

Agent: euler
---
 analysis/deps/hotspots.md    | 114 +++++++++++++++--------------
 analysis/deps/limitations.md | 135 +++++++++++++++++++++++------------
 2 files changed, 153 insertions(+), 96 deletions(-)

diff --git a/analysis/deps/hotspots.md b/analysis/deps/hotspots.md
index ab65dd2..f31525e 100644
--- a/analysis/deps/hotspots.md
+++ b/analysis/deps/hotspots.md
@@ -1,69 +1,79 @@
 # Coupling Hotspots
 
+**Generated**: 2025-02-02  
+**Method**: Fan-in/fan-out analysis from dependency graph
+
 ## High Fan-In Files (Most Depended Upon)
 
-Files with disproportionately high incoming dependencies.
+These files are imported by many other files. Changes here have wide impact.
 
-| File | Fan-In | Crate | Role |
-|------|--------|-------|------|
-| ui_writer.rs | 15 | g3-core | UI abstraction trait |
-| g3_status.rs | 10 | g3-cli | Status message formatting |
-| simple_output.rs | 8 | g3-cli | Output helper |
-| context_window.rs | 6 | g3-core | Token/context management |
-| template.rs | 6 | g3-cli | Template processing |
-| paths.rs | 5 | g3-core | Path utilities |
-
-### Evidence: ui_writer.rs (fan-in: 15)
-
-Depended on by:
-- g3-cli: accumulative.rs, agent_mode.rs, autonomous.rs, commands.rs, interactive.rs, task_execution.rs, ui_writer_impl.rs, utils.rs
-- g3-core: compaction.rs, feedback_extraction.rs, lib.rs, retry.rs, tool_dispatch.rs, tools/*.rs
-
-### Evidence: g3_status.rs (fan-in: 10)
-
-Depended on by:
-- commands.rs, interactive.rs, simple_output.rs, task_execution.rs, and others in g3-cli
+| File | Fan-In | Dependents |
+|------|--------|------------|
+| `g3-core/src/lib.rs` | 18 | streaming_parser, context_window, acd, streaming, stats, retry, feedback_extraction, task_result, tool_dispatch, tools/* |
+| `g3-core/src/ui_writer.rs` | 14 | retry, compaction, feedback_extraction, tool_dispatch, tools/{acd,executor,shell,research,file_ops,plan,memory,misc,webdriver} |
+| `g3-cli/src/simple_output.rs` | 9 | utils, interactive, autonomous, coach_feedback, accumulative, task_execution, commands, agent_mode |
+| `g3-cli/src/template.rs` | 6 | project_files, accumulative, commands, embedded_agents, agent_mode, interactive |
+| `g3-core/src/paths.rs` | 6 | acd, session, context_window, tools/{executor,shell,plan} |
+| `g3-core/src/context_window.rs` | 5 | compaction, stats, streaming, session, task_result |
+| `g3-cli/src/g3_status.rs` | 5 | simple_output, interactive, task_execution, commands |
+| `g3-cli/src/display.rs` | 4 | interactive, ui_writer_impl, agent_mode |
+| `g3-cli/src/ui_writer_impl.rs` | 4 | autonomous, coach_feedback, accumulative, agent_mode |
+| `g3-core/src/utils.rs` | 3 | tools/{shell,file_ops} |
 
 ## High Fan-Out Files (Most Dependencies)
 
-Files with disproportionately high outgoing dependencies.
+These files import many other modules. They are integration points.
 
-| File | Fan-Out | Crate | Role |
-|------|---------|-------|------|
-| agent_mode.rs | 13 | g3-cli | Agent mode entry point |
-| lib.rs | 13 | g3-core | Core library root |
-| commands.rs | 12 | g3-cli | Command handlers |
-| interactive.rs | 12 | g3-cli | Interactive REPL |
-| accumulative.rs | 11 | g3-cli | Accumulative mode |
-| planner.rs | 8 | g3-planner | Planning orchestration |
+| File | Fan-Out | Dependencies |
+|------|---------|-------------|
+| `g3-cli/src/interactive.rs` | 11 | g3-core, completion, commands, display, g3_status, project, project_files, simple_output, input_formatter, template, task_execution, utils |
+| `g3-cli/src/agent_mode.rs` | 11 | g3-core, project_files, display, language_prompts, simple_output, embedded_agents, ui_writer_impl, interactive, template, project, cli_args |
+| `g3-cli/src/accumulative.rs` | 8 | g3-core, autonomous, cli_args, interactive, simple_output, ui_writer_impl, utils, template |
+| `g3-cli/src/commands.rs` | 7 | g3-core, completion, g3_status, simple_output, project, template, task_execution |
+| `g3-core/src/tools/executor.rs` | 7 | g3-config, background_process, pending_research, paths, ui_writer, webdriver_session, lib (ToolCall) |
+| `g3-cli/src/autonomous.rs` | 5 | g3-core, coach_feedback, metrics, simple_output, ui_writer_impl |
+| `g3-core/src/compaction.rs` | 4 | g3-providers, context_window, provider_config, ui_writer |
+| `g3-core/src/tool_dispatch.rs` | 4 | tools/executor, tools/mod, ui_writer, lib (ToolCall) |
+| `g3-cli/src/ui_writer_impl.rs` | 4 | g3-core, filter_json, display, streaming_markdown |
+| `g3-core/src/streaming.rs` | 4 | g3-providers, context_window, streaming_parser, lib (ToolCall) |
 
-### Evidence: agent_mode.rs (fan-out: 13)
+## Cross-Crate Coupling Points
 
-Depends on:
-- g3-core: Agent, ui_writer::UiWriter
-- Internal: project_files, display, language_prompts, simple_output, embedded_agents, ui_writer_impl, interactive, template
+Files that bridge multiple crates:
 
-### Evidence: g3-core/lib.rs (fan-out: 13)
+| File | Cross-Crate Imports | Crates Touched |
+|------|---------------------|----------------|
+| `g3-core/src/lib.rs` | 2 | g3-config, g3-providers |
+| `g3-core/src/webdriver_session.rs` | 1 | g3-computer-control |
+| `g3-core/src/tools/webdriver.rs` | 1 | g3-computer-control |
+| `g3-core/src/tools/executor.rs` | 1 | g3-config |
+| `g3-core/src/tools/research.rs` | 1 | g3-config |
+| `g3-core/src/provider_registration.rs` | 2 | g3-config, g3-providers |
+| `g3-planner/src/llm.rs` | 3 | g3-config, g3-core, g3-providers |
 
-Depends on:
-- External crates: g3-config, g3-providers
-- Internal modules: ui_writer, context_window, paths, compaction, streaming, tools, etc.
+## Crate-Level Coupling
 
-## Cross-Crate Coupling
-
-| Source Crate | Target Crate | Edge Count |
-|--------------|--------------|------------|
-| g3-cli | g3-core | 35 |
-| g3-core | g3-providers | 10 |
-| g3-core | g3-config | 5 |
-| g3-planner | g3-core | 4 |
-| g3-planner | g3-providers | 3 |
-| g3-core | g3-computer-control | 2 |
+| Crate | Outgoing Deps | Incoming Deps | Coupling Score |
+|-------|---------------|---------------|----------------|
+| g3-cli | 5 | 1 | High (consumer) |
+| g3-core | 4 | 3 | High (hub) |
+| g3-planner | 3 | 1 | Medium |
+| g3-providers | 0 | 5 | High (foundation) |
+| g3-config | 0 | 5 | High (foundation) |
+| g3-computer-control | 0 | 2 | Low |
+| g3-execution | 0 | 1 | Low |
+| studio | 0 | 0 | Isolated |
 
 ## Observations
 
-1. **ui_writer.rs** is a central abstraction point; changes here affect 15+ files
-2. **g3-cli** files have high fan-out due to orchestration responsibilities
-3. **g3-core/lib.rs** is the primary API surface with expected high coupling
-4. **g3_status.rs** and **simple_output.rs** form a UI utility cluster in g3-cli
-5. **tools/*.rs** files consistently depend on ui_writer and ToolCall types
+1. **g3-core/src/lib.rs** is the primary coupling hotspot. It defines `Agent`, `ToolCall`, and other core types used throughout the codebase.
+
+2. **g3-core/src/ui_writer.rs** defines the `UiWriter` trait used by all tool implementations for output. High fan-in is expected for a trait definition.
+
+3. **g3-cli/src/simple_output.rs** is a utility wrapper used by most CLI modules. High fan-in indicates it's a well-factored common dependency.
+
+4. **g3-cli/src/interactive.rs** and **g3-cli/src/agent_mode.rs** have the highest fan-out, as expected for top-level orchestration modules.
+
+5. **g3-providers** and **g3-config** are foundation crates with zero outgoing dependencies and high incoming dependencies. This is the expected pattern for leaf crates.
+
+6. **studio** is completely isolated from the g3 crate ecosystem.
diff --git a/analysis/deps/limitations.md b/analysis/deps/limitations.md
index 8df2c0c..ed33162 100644
--- a/analysis/deps/limitations.md
+++ b/analysis/deps/limitations.md
@@ -1,67 +1,114 @@
 # Analysis Limitations
 
-## What Was Observed
-
-| Category | Method | Coverage |
-|----------|--------|----------|
-| Crate dependencies | Cargo.toml parsing | Complete |
-| Module structure | `mod` declarations in lib.rs/main.rs | Complete |
-| File imports | `use g3_*` and `use crate::` patterns | Partial |
-| Submodule structure | mod.rs file inspection | Complete |
+**Generated**: 2025-02-02
 
 ## What Could Not Be Observed
 
-### 1. Implicit Dependencies
+### 1. Dynamic/Runtime Dependencies
 
-- **Trait implementations**: A file implementing a trait from another module creates a dependency not captured by `use` statements
-- **Type aliases**: Types re-exported through `pub use` chains
-- **Derive macros**: Dependencies introduced by `#[derive(...)]`
+- **Plugin loading**: Any runtime module loading via `dlopen` or similar
+- **Reflection-based imports**: Dependencies resolved at runtime
+- **Configuration-driven imports**: Modules loaded based on config values
 
-### 2. Dynamic Patterns
+### 2. Macro-Generated Code
 
-- **Trait objects**: `dyn Trait` usage creates runtime dependencies
-- **Generic bounds**: `T: SomeTrait` constraints
-- **Associated types**: Dependencies through associated type resolution
+- **Procedural macros**: Code generated by `#[derive(...)]` and custom proc macros
+- **Declarative macros**: `macro_rules!` expansions that generate `use` statements
+- **Build script outputs**: Code generated by `build.rs` files
 
 ### 3. Conditional Compilation
 
-- **Platform-specific code**: `#[cfg(target_os = "...")]` blocks not evaluated
-- **Feature flags**: `#[cfg(feature = "...")]` dependencies not traced
-- **Test-only code**: `#[cfg(test)]` modules excluded
+- **Platform-specific code**: `#[cfg(target_os = "...")]` blocks are included regardless of target
+- **Feature flags**: `#[cfg(feature = "...")]` gated code is included unconditionally
+- **Test-only code**: `#[cfg(test)]` modules are excluded from analysis
 
-### 4. Build System
+### 4. Re-exports and Transitive Dependencies
 
-- **build.rs**: Build script dependencies not analyzed
-- **Procedural macros**: Macro crate dependencies not traced
-- **Workspace-level features**: Feature unification effects not modeled
+- **`pub use` chains**: Transitive re-exports are not fully traced
+- **Glob imports**: `use module::*` does not enumerate specific items
+- **Prelude imports**: Implicit prelude items are not tracked
 
-### 5. Excluded Files
+### 5. External Crate Dependencies
 
-| Category | Count | Reason |
-|----------|-------|--------|
-| Test files (`/tests/`) | ~40 | Out of scope |
-| Example files (`/examples/`) | ~10 | Out of scope |
-| Worktree copies | ~100 | Duplicates |
+- **Third-party crates**: Only internal g3 workspace crates are analyzed
+- **Workspace dependency versions**: Version constraints not analyzed
+- **Optional dependencies**: Not distinguished from required dependencies
 
 ## What Was Inferred
 
-| Inference | Basis | Confidence |
-|-----------|-------|------------|
-| Layer assignment | Topological sort of crate deps | High |
-| Fan-in/fan-out metrics | Edge counting | High |
-| Module-to-file mapping | Naming convention (mod.rs, *.rs) | High |
-| Entrypoints | lib.rs/main.rs presence | High |
+### 1. Module Hierarchy
+
+Module parent-child relationships inferred from:
+- `mod` declarations in `lib.rs` and `mod.rs` files
+- File system structure (`foo/mod.rs` implies `foo` module)
+
+**Confidence**: High - Rust module system is deterministic
+
+### 2. Crate Dependencies
+
+Crate-level dependencies extracted from:
+- `Cargo.toml` `[dependencies]` sections
+- `path = "..."` declarations for workspace crates
+
+**Confidence**: High - Cargo.toml is authoritative
+
+### 3. File-Level Imports
+
+File imports extracted via regex pattern matching:
+- `^use (g3_|crate::)` for internal imports
+- `^(pub )?mod ` for module declarations
+
+**Confidence**: Medium-High - May miss unusual import patterns
+
+### 4. Fan-In/Fan-Out Counts
+
+Coupling metrics derived from edge counts in dependency graph.
+
+**Confidence**: Medium - Depends on completeness of edge extraction
 
 ## What May Invalidate Conclusions
 
-1. **Hidden re-exports**: If `g3-core/lib.rs` re-exports types from submodules, actual coupling may be higher
-2. **Macro-generated code**: Macros like `#[derive(Serialize)]` add implicit serde dependency
-3. **Runtime plugin loading**: If any crate loads code dynamically, static analysis misses it
-4. **Workspace member changes**: Adding/removing crates from workspace invalidates crate-level graph
+### 1. Code Changes
 
-## Recommendations for Improved Analysis
+This analysis reflects the codebase state at generation time. Any of the following invalidate the analysis:
+- New files added
+- Import statements changed
+- Module structure reorganized
+- Cargo.toml dependencies modified
 
-1. Use `cargo metadata` for authoritative crate graph
-2. Use `cargo tree` for transitive dependency analysis
-3. Use `rust-analyzer` for semantic import resolution
-4. Parse AST for type references beyond `use` statements
+### 2. Incomplete Extraction
+
+The regex-based extraction may miss:
+- Multi-line `use` statements with unusual formatting
+- Imports inside function bodies
+- Imports in macro invocations
+- `extern crate` declarations (deprecated but valid)
+
+### 3. Test Code Exclusion
+
+Test files (`tests/*.rs`, `#[cfg(test)]` modules) are excluded. Test-only dependencies and coupling patterns are not reflected.
+
+### 4. Example Code Exclusion
+
+Example files (`examples/*.rs`) are excluded from the graph.
+
+### 5. Build Script Dependencies
+
+`build.rs` files may introduce compile-time dependencies not reflected in the import graph.
+
+## Extraction Method Details
+
+| Aspect | Method | Tool |
+|--------|--------|------|
+| Crate dependencies | Cargo.toml parsing | Manual inspection |
+| Module declarations | Regex: `^(pub )?mod ` | ripgrep |
+| Internal imports | Regex: `^use (g3_\|crate::)` | ripgrep |
+| File enumeration | `find crates -name "*.rs"` | find |
+| Cycle detection | Manual graph traversal | N/A |
+
+## Recommendations for Future Analysis
+
+1. **Use cargo metadata**: `cargo metadata --format-version 1` provides authoritative dependency information
+2. **Use rust-analyzer**: LSP-based analysis would capture macro expansions
+3. **Use cargo-depgraph**: Specialized tool for Rust dependency visualization
+4. **Include test coverage**: Analyze test files separately for test-specific coupling