Spectra — spectra

Architecture 84 B+

Security 89 A-

Quality 82 B

Documentation 85 B+

Maintainability 83 B+

Performance 83 B+

Executive Summary

Your codebase scores B+ (85/100) — strong security with quality gaps

Top Strengths

Security A- (89)

Documentation B+ (86)

Architecture B+ (85)

Key Concerns

Quality B (82)

Performance B+ (83)

Maintainability B+ (84)

Severity Distribution

medium (14) low (20) info (4)

38 findings · 6 agents · 257s · ~62h tech debt

What to Fix First

01> medium Composition root has grown beyond pure DI wiring (mixed responsibilities) src/spectra/infrastructure/main.py:280
Extract `_build_sarif` into a dedicated `SarifAdapter` (or extend `ReportAdapter`) implementing a `ReportPort.render(report, format, path)` contract. Move `_read_key_source_files`/`_prioritize_source_files` into a `SourceFileSelector` adapter or a use-case helper. Keep main.py focused on construction.
02> medium Module-level mutable globals for DI in CLI controller src/spectra/adapters/cli_controller.py:110
Encapsulate the injected dependencies in a `CliContext` dataclass stored on the Typer app's `obj` (via `ctx.obj`), or build the Typer app inside a factory function `build_cli(analyzer_factory, cache_provider) -> Typer` so dependencies flow in via closure rather than module globals.
03> medium BaseAgent.parse_output / format_result violate Liskov for non-finding agents src/spectra/infrastructure/agents/base_agent.py:55
Generalize `BaseAgent` to be parametric in output type (e.g., `BaseAgent[T]` with abstract `parse_result(parsed) -> T`) or split into two ABCs: `FindingProducingAgent` for specialists and `StructuredOutputAgent` for MetaPrompter/CritiqueAgent. This avoids the double-parse and the empty-tuple workaround.
04> medium Composition root performs use-case-level orchestration (Stage 1 INGEST and Stage 6 REPORT) src/spectra/infrastructure/main.py:145
Move INGEST and REPORT stages into `analyze_repository` (or a top-level `run_pipeline` use case) so main.py only constructs ports and calls a single use-case entry point. The use case should accept a `ReportPort` and call it for rendering, keeping format-branching out of the composition root.
05> medium CritiqueAgent.validate_output silently discards parsed structure and returns empty tuple src/spectra/infrastructure/agents/critique_agent.py:155
Either store the parsed critique result on the instance during validate_output (so get_critique_result returns it without re-parsing), or extend AgentOutput with an optional critique_payload field so the contract is honored without dual entry points.

B+ 0 / 100

Industry median: 65 · Well above industry median for all projects B grades represent well-maintained codebases with room for improvement

Architecture85

Security89

Quality82

Documentation86

Maintainability84

Performance83

Architecture

0 B+

Security

0 A-

Quality

0 B

Documentation

0 B+

Maintainability

0 B+

Performance

0 B+

Findings

Critical

Duration

Cost

Agents

Analysis Coverage

Agents

463K

Tokens Used

4m 16s

Duration

$5.09

API Cost

Hallucinations Removed

Agents Used

Architecture Security Quality Documentation Dependency Performance

3 findings removed (referenced non-existent files)

File Hotspot Heatmap

15

src/spectra/infrastructure/main.py
7

src/spectra/adapters/cli_controller.py
3

pyproject.toml
2

src/spectra/infrastructure/agents/specialist_agent.py
2

src/spectra/entities/models.py
1

src/spectra/infrastructure/agents/agent_factory.py
1

src/spectra/infrastructure/agents/base_agent.py
1

src/spectra/infrastructure/agents/critique_agent.py
1

src/spectra/infrastructure/agents/specialist_prompts.py
1

src/spectra/infrastructure/agents/meta_prompter.py
1

src/spectra/entities/enums.py
1

src/spectra/entities/errors.py
1

src/spectra/use_cases/orchestrate_agents.py
1

src/spectra/infrastructure/retry_decorator.py

Filter

Strengths

✓ Strong architectural foundation: ports, frozen entities, and explicit composition root — Positive findings: (1) Entities are frozen Pydantic models with no spectra-internal imports — pure inner layer. (2) Enums use `Literal` types for JSON-safety. (3) `interfaces.py` defines Protocol-based ports (`LLMGateway`, `CachePort`, `GitPort` implied) enabling structural subtyping. (4) main.py is clearly demarcated as the composition root with thorough docstrings explaining DI wiring. (5) Decorator chain (Logging → Retry → Anthropic) is composed at construction time, not via inheritance. (6) Adapter layer (`adapters/`) is correctly separated from infrastructure (`infrastructure/`). (7) Per-layer `__init__.py` files document the layer's role and dependency rules. This represents mature Clean Architecture discipline.
✓ Tempdir cleanup uses ignore_errors=True, masking failure to remove cloned repo — `shutil.rmtree(workspace_dir, ignore_errors=True)` in the `finally` block silently swallows cleanup errors. If cleanup fails (e.g. file lock on Windows, permission issue), cloned source code — which may include secrets, proprietary code, or `.env` files from the analyzed repo — persists in `/tmp/spectra-*` past process exit. The `0o700` perms limit exposure to other users but not to the same user's other processes or backups. CWE-459 (Incomplete Cleanup).

CritiqueAgent validated findings using extended thinking. 5 of 38 findings were individually confirmed.

Architecture (8)

medium Composition root has grown beyond pure DI wiring (mixed responsibilities) ~4.0h ▶

src/spectra/infrastructure/main.py:280-360

infrastructure/main.py now contains: DI wiring, workspace allocation, file heuristics (`_read_key_source_files`, `_prioritize_source_files`), SARIF report builder (`_build_sarif`), cache version composition (`_composite_model_versions`, `_composite_prompt_versions`), and report rendering branching. A composition root should primarily wire dependencies; additional orchestration logic belongs in use cases or dedicated adapters. The SARIF builder in particular is a presentation concern that should live in an adapter alongside `ReportAdapter`.

Recommendation: Extract `_build_sarif` into a dedicated `SarifAdapter` (or extend `ReportAdapter`) implementing a `ReportPort.render(report, format, path)` contract. Move `_read_key_source_files`/`_prioritize_source_files` into a `SourceFileSelector` adapter or a use-case helper. Keep main.py focused on construction.

medium Module-level mutable globals for DI in CLI controller ~3.0h ▶

src/spectra/adapters/cli_controller.py:110-130

`cli_controller.py` uses module-level `_analyzer_factory` and `_cache_provider` globals mutated via `set_analyzer_factory` / `set_cache_provider`. This is a pragmatic Typer integration, but it makes the CLI harder to test in isolation, prevents concurrent invocations with different factories, and relies on import-time global state. The `global` keyword usage and `noqa: PLW0603` suppressions are smells indicating the pattern is suboptimal.

Recommendation: Encapsulate the injected dependencies in a `CliContext` dataclass stored on the Typer app's `obj` (via `ctx.obj`), or build the Typer app inside a factory function `build_cli(analyzer_factory, cache_provider) -> Typer` so dependencies flow in via closure rather than module globals.

medium BaseAgent.parse_output / format_result violate Liskov for non-finding agents ~4.0h ▶

src/spectra/infrastructure/agents/base_agent.py:55-75

`BaseAgent.run()` calls `validate_output(parsed) -> tuple[Finding, ...]` and then `format_result(findings, ...)` on the result. However, `MetaPrompter.validate_output` and `CritiqueAgent.validate_output` always return `()` because their outputs are not findings — they are plans and critiques. Callers must then call `get_plan()` or `get_critique_result()` separately by re-parsing `raw_response`, parsing the same JSON twice. This indicates `BaseAgent`'s Template Method is over-fitted to specialists.

Recommendation: Generalize `BaseAgent` to be parametric in output type (e.g., `BaseAgent[T]` with abstract `parse_result(parsed) -> T`) or split into two ABCs: `FindingProducingAgent` for specialists and `StructuredOutputAgent` for MetaPrompter/CritiqueAgent. This avoids the double-parse and the empty-tuple workaround.

medium Composition root performs use-case-level orchestration (Stage 1 INGEST and Stage 6 REPORT) ~6.0h ▶

src/spectra/infrastructure/main.py:145-245

`_run_analysis` in main.py executes Stage 1 (clone, validate size, get file tree, read key source files) and Stage 6 (render report) directly, while delegating Stages 2–5 to `analyze_repository`. This split is asymmetric and leaks pipeline orchestration into the composition root. The `PipelineContext` is also constructed in main.py, which means changing the pipeline shape requires touching main.py rather than the use case.

Recommendation: Move INGEST and REPORT stages into `analyze_repository` (or a top-level `run_pipeline` use case) so main.py only constructs ports and calls a single use-case entry point. The use case should accept a `ReportPort` and call it for rendering, keeping format-branching out of the composition root.

low Composition root reaches into infrastructure internals to compute cache key versions ~1.5h ▶

src/spectra/infrastructure/main.py:60-65

main.py imports private symbols `_SYSTEM_PROMPT` from critique_agent and `_SHARED_GUIDANCE` from specialist_prompts to compute prompt version digests. While this is documented as 'preserving the dependency rule by keeping prompt knowledge in the composition root,' it actually couples main.py to private module internals (leading underscore names), creating a fragile dependency. A refactor that renames or restructures these constants will silently break cache key composition.

Recommendation: Expose a public API in the agents package (e.g., `get_prompt_version_inputs()` returning the bytes to digest) so main.py depends on a stable contract rather than module-private constants. Alternatively, encapsulate the digest computation in a `PromptVersions` helper class within the agents package.

low AgentFactory leaks specialist role list duplication with specialist_prompts ~0.5h ▶

src/spectra/infrastructure/agents/agent_factory.py:80-95

`AgentFactory.create_specialists()` hardcodes the list of 6 specialist roles, but the canonical source of truth is the `SPECIALIST_CONFIGS` dictionary in `specialist_prompts.py`. The two can drift: adding a new specialist to `SPECIALIST_CONFIGS` will not automatically include it in `create_specialists()`. The `progress_reporter.py` `_SPECIALIST_ROLES` constant is a third copy of this list.

Recommendation: Derive the specialist role list from `SPECIALIST_CONFIGS.keys()` (sorted for determinism) so adding a new specialist requires changing one place only. Export a canonical `SPECIALIST_ROLES` tuple from `specialist_prompts.py` and reuse it in `progress_reporter.py`.

low Circular import risk: specialist_agent imports from use_cases at runtime ~0.2h ▶

src/spectra/infrastructure/agents/specialist_agent.py:13-14

`specialist_agent.py` imports `LLMGateway` directly at runtime from `spectra.use_cases.interfaces` (not under TYPE_CHECKING). This is correct for the dependency rule (infrastructure → use_cases is allowed inward), but the same module also imports `MIN_CONFIDENCE` from `entities.models`, mixing entity and use-case dependencies. base_agent.py also imports `LLMGateway` at runtime. While currently fine, runtime imports of Protocols (vs TYPE_CHECKING) add load-time coupling that is unnecessary since Protocols use structural typing.

Recommendation: Move `LLMGateway` import under `if TYPE_CHECKING:` block (consistent with critique_agent.py and meta_prompter.py which already do this). This decouples module load order and clarifies that the gateway is a structural type.

low PipelineContext over-injection suggests missing abstraction ~2.5h ▶

src/spectra/infrastructure/main.py:195-215

`PipelineContext` (constructed in main.py) carries 11 fields including `meta_prompter`, `specialists`, `critique_agent`, `git_port`, `observer`, `source_files`, `cache_port`, `cache_key_factory`, `force_cache_bypass`, `request`, `codebase`. This is a parameter object, but the breadth suggests `analyze_repository` is doing too much. Mixing transient state (source_files, codebase) with long-lived ports (git_port, cache_port) and policy (force_cache_bypass) in one struct couples unrelated concerns.

Recommendation: Split into two structures: `PipelineDependencies` (immutable per-process — agents, ports, observer, key factory) and `PipelineRequest` (per-run — request, codebase, source_files, force flag). The use case method then has a clearer signature: `analyze_repository(deps, request)`.

estimated effort: ~23h

Security (6)

low URL validation regex allows credentials in authority and arbitrary characters in path ~2.0h ✓ validated ▶

src/spectra/adapters/cli_controller.py:30-33

The `_URL_PATTERN` regex in `cli_controller.py` matches `https://[host](/[^\s]*)?$` but does not reject userinfo (e.g. `https://user:pass@evil.com/legit-looking-path`) or unusual characters that may confuse downstream `git clone`. Combined with the fact that the URL is passed to GitPython for cloning, this widens the input surface for SSRF/credential-injection style abuse. CWE-20 (Improper Input Validation), OWASP A10:2021 SSRF.

Recommendation: Use `urllib.parse.urlparse` to extract scheme/netloc/path, reject any URL with `userinfo` (`@` in netloc), restrict netloc to a known allow-list of hosts (github.com, gitlab.com, bitbucket.org) when feasible, and disallow control characters in the path. Pair with the existing GitAdapter SSRF/host checks (which the comments describe) for defense-in-depth.

low Local path validation has TOCTOU window between symlink check and use ~3.0h ▶

src/spectra/adapters/cli_controller.py:47-64

`_validate_local_path` checks `expanded.is_symlink()` and `(expanded / '.git').exists()` but the path is later passed to `GitPort.prepare_workspace` for indexing. Between validation and use an attacker with write access to that directory could swap the path for a symlink (TOCTOU). Furthermore the `..` check is on the user-supplied raw input only — symlinked components inside the directory tree are not blocked. CWE-367 (TOCTOU Race Condition), CWE-22 (Path Traversal).

Recommendation: Resolve the path with `Path(...).resolve(strict=True)` once and pass the resolved canonical path downstream. In `GitAdapter.read_file`, ensure each resolved file path remains under the canonical workspace root (`commonpath` check) to prevent symlink escapes during indexing.

low Unredacted exception message printed to console (may leak secrets in tracebacks) ~2.0h ▶

src/spectra/adapters/cli_controller.py:215-220

In `cli_controller.analyze`, the catch-all `except Exception as exc` prints `f"Unexpected error: {exc}"` and, when `--verbose` is set, dumps a full `traceback.format_exc()` to the terminal. If an exception bubbles up from the Anthropic SDK or HTTP layer it can include the request URL, headers, or partially-sanitized API key fragments. CWE-209 (Information Exposure Through an Error Message), CWE-532 (Insertion of Sensitive Information into Log File).

Recommendation: Pipe unexpected exceptions through the same redaction logic used by `LoggingDecorator` (which the module docstring notes redacts `sk-ant-*`). Apply a regex scrub for `sk-ant-[A-Za-z0-9_-]+` and common bearer-token shapes before printing the message or traceback. Consider gating full tracebacks behind an explicit `--debug` flag separate from `--verbose`.

low SARIF/HTML report fields are populated with attacker-controlled finding text without explicit encoding guarantees ~2.0h ✓ validated ▶

src/spectra/infrastructure/main.py:286-318

`_build_sarif` and the Jinja2 HTML template render `Finding.title`, `description`, `recommendation`, and `code_snippet` — fields that ultimately come from LLM output of attacker-controlled repository contents (filenames, code snippets, embedded HTML, JavaScript, or markdown). For SARIF this is JSON-encoded so it is safe; for the HTML report (`report_renderer.render`), the security depends on Jinja2 autoescape being enabled — which is NOT visible in the provided code. CWE-79 (Cross-site Scripting), OWASP A03:2021 Injection.

Recommendation: Confirm `ReportAdapter` constructs its `Environment` with `autoescape=select_autoescape(['html', 'htm', 'j2'])` (or `autoescape=True`). Add a unit test that renders a finding containing `<script>alert(1)</script>` and asserts the output escapes it. For `code_snippet` rendered inside `<pre>`, still escape — autoescape covers this. Also set `Content-Security-Policy` via `<meta>` in the template if the report may be hosted online.

low Repository name derived from URL is used unsafely in display without sanitization ~0.5h ▶

src/spectra/infrastructure/main.py:261-263

`_derive_repo_name` returns `source.rstrip('/').split('/')[-1].removesuffix('.git')`. This name flows into the Rich console (`console.print(f"target: {repo_name}")`) and the HTML report. Rich interprets `[...]` as markup, so a repo URL ending in `.../[red]injected[/red].git` would render colored text in the terminal — a low-impact UX issue but a precedent for richer markup injection if the value is later embedded in HTML without escaping. CWE-117 (Improper Output Neutralization for Logs).

Recommendation: When passing user-controlled values into Rich, use `console.print(..., markup=False)` or wrap the value with `rich.markup.escape(repo_name)`. For HTML, rely on Jinja2 autoescape (and verify it is enabled — see related finding).

info Heuristic file reader silently swallows all read errors ~0.5h ▶

src/spectra/infrastructure/main.py:313-319

`_read_key_source_files` uses `except Exception: continue` (with `# noqa: S112`) when reading source files. While the `noqa` shows intent, this masks security-relevant failures such as path-traversal attempts caught by `GitPort.read_file`, file size limit violations, or symlink rejections. Without logging, an attacker probing the indexing path gets no visibility but neither do operators investigating an incident. CWE-755 (Improper Handling of Exceptional Conditions).

Recommendation: Replace the bare `except Exception` with explicit catches for `OSError`, `GitError`, and the size-limit exception. Log at DEBUG so operators can opt into visibility via `--verbose` without producing noise on healthy runs.

estimated effort: ~11h

Quality (7)

medium CritiqueAgent.validate_output silently discards parsed structure and returns empty tuple ~2.0h ▶

src/spectra/infrastructure/agents/critique_agent.py:155-168

validate_output checks only that required keys exist, then returns (). The actual validated/rejected/severity-adjusted findings live in `parsed` but are never returned through the BaseAgent contract — callers must use the side-channel get_critique_result() and re-parse the raw output. This is duplicated parsing work and an inconsistency with the Template Method contract: validate_output advertises (Finding, ...) but cannot meaningfully fulfill it for critique. The dual-path design (validate_output + get_critique_result) is a code smell that invites callers to forget one of them.

Recommendation: Either store the parsed critique result on the instance during validate_output (so get_critique_result returns it without re-parsing), or extend AgentOutput with an optional critique_payload field so the contract is honored without dual entry points.

medium Bare `except Exception` swallows file-read errors silently with noqa: S112 ~0.5h ▶

src/spectra/infrastructure/main.py:326-332

_read_key_source_files catches every Exception during file reading or token counting and silently `continue`s. The noqa: S112 acknowledges this but no logging occurs. Real I/O errors (permission denied, decoding errors, mid-flight corruption) become invisible, which is a debuggability hazard especially for the heuristic source-file pipeline where missing files materially change specialist input quality.

Recommendation: Narrow the except clause to (OSError, UnicodeDecodeError) and log at DEBUG level with the file path and exception class. This preserves resilience while making silent skips diagnosable.

medium Validation strategy in SpecialistAgent.validate_output uses unsafe coercions ~1.5h ▶

src/spectra/infrastructure/agents/specialist_agent.py:73-96

validate_output uses str(...)/int(...)/float(...) on raw LLM dict values without try/except. If the LLM produces a non-numeric line_start (e.g. 'unknown'), int() raises ValueError, the entire batch fails, and a single bad finding kills all valid findings in that response. Severity is also coerced via str() but never validated against the Severity Literal — invalid severities will pass into Pydantic and fail there, yielding a less actionable error.

Recommendation: Wrap each finding construction in try/except (ValueError, ValidationError) and skip individual bad findings with a debug log. Validate severity ∈ {critical,high,medium,low,info} explicitly before constructing Finding so the failure mode is clear.

medium _run_analysis function exceeds 100 lines and has 7 boolean/string parameters ~3.0h ▶

src/spectra/infrastructure/main.py:90-215

_run_analysis in main.py is the composition root's async entry point and runs ~120 lines with 7 parameters (skip_critique, output_format, verbose, force, no_cache, plus the two required). It mixes DI wiring, ingest stage, agent factory, pipeline call, and three output-format branches in one function. PLR0913 is globally ignored, but the function still has high cognitive load — and the Stage 6 REPORT branch logic (json/sarif/else) is duplicated logic that belongs in a presenter.

Recommendation: Extract three helpers: (a) _build_pipeline_context(...) for DI wiring through PipelineContext, (b) _emit_report(report, output_path, fmt, renderer) for Stage 6 dispatch, and (c) bundle the 7 flags into a small frozen RunOptions model. Target the function under 40 lines.

medium Module-level mutable globals (_analyzer_factory, _cache_provider) create test isolation hazards ~2.0h ▶

src/spectra/adapters/cli_controller.py:137-158

cli_controller.py uses module-level globals set via set_analyzer_factory and set_cache_provider with `global` declarations and noqa: PLW0603. These globals persist across test invocations and across sequential CLI calls within one process, creating ordering dependencies and making CLI tests require explicit teardown. There is no reset_for_tests() seam.

Recommendation: Either (a) thread the analyzer/cache provider through a small CLIContext object passed to the Typer commands, or (b) at minimum add a module-level reset() function that nulls both globals, and call it in conftest.py autouse fixture.

low Duplicate model-version literals risk drift in cache key composition ~0.5h ▶

src/spectra/infrastructure/main.py:263-270

_composite_model_versions hardcodes 'claude-opus-4-7' twice for MetaPrompter and CritiqueAgent, while specialist_prompts.py defines _OPUS = 'claude-opus-4-7' and meta_prompter.py / critique_agent.py also pin the same string in their __init__. Five separate sources of truth for the same model literal — a model version bump must touch all of them or cache invalidation will be inconsistent.

Recommendation: Define a single MODEL_OPUS constant in entities/enums.py or a dedicated models.py and import it from MetaPrompter, CritiqueAgent, specialist_prompts, AGENT_MODELS, and _composite_model_versions.

info Missing __all__ in agents/specialist_prompts.py allows accidental private import drift ~0.5h ▶

src/spectra/infrastructure/agents/specialist_prompts.py:595-605

specialist_prompts.py exports module-level constants (_SHARED_GUIDANCE, ARCHITECTURE_PROMPT, ...PROMPT, SPECIALIST_CONFIGS) but defines no __all__. main.py reaches into the module to grab _SHARED_GUIDANCE (underscore-prefixed = nominally private). Either the convention should be honored (rename to SHARED_GUIDANCE and export), or main.py should not import the private name.

Recommendation: Rename _SHARED_GUIDANCE to SHARED_GUIDANCE, add __all__ = ['SHARED_GUIDANCE', 'SPECIALIST_CONFIGS', 'ARCHITECTURE_PROMPT', ...], and update main.py import accordingly.

estimated effort: ~10h

Documentation (6)

low Stale model/effort references in pipeline info banner ~0.5h ✓ validated ▶

src/spectra/adapters/cli_controller.py:134-142

The CLI banner advertises 'sonnet-4.5 planner' and 'opus-4.6' for specialists/critique, but the actual code uses 'claude-opus-4-7' for all 8 agents (per AGENT_MODELS, SPECIALIST_CONFIGS, MetaPrompter, and CritiqueAgent). User-facing documentation embedded in the CLI contradicts the implementation, which will mislead users and undermine trust in the report.

Recommendation: Update _PIPELINE_INFO to reflect the current model identifiers and effort levels (opus-4.7 across all agents; medium for MetaPrompter, xhigh for specialists, high+adaptive thinking for Critique).

low MetaPrompter docstring/module header contradicts actual model ~0.5h ✓ validated ▶

src/spectra/infrastructure/agents/meta_prompter.py:1-10

The module docstring at meta_prompter.py states 'MetaPrompter agent — Sonnet 4.5, planning from file tree only' and the class docstring repeats 'Sonnet 4.5, never sees full code', but the constructor wires model='claude-opus-4-7' with effort='medium'. This inconsistency will confuse contributors reading the code and may cause incorrect cost/latency assumptions.

Recommendation: Update the module docstring and class docstring to read 'Opus 4.7, medium effort'. Also update the prompt-caching note's date if applicable.

low estimate_cost docstring contradicts implementation ~0.5h ▶

src/spectra/entities/models.py

The docstring of estimate_cost() in models.py says 'Sonnet is used for MetaPrompter; Opus for all others', but _MODEL_COST maps every agent (including meta_prompter) to _OPUS_AVG_PER_1K. The docstring is misleading and will confuse anyone reading cost-estimation logic or trying to extend pricing.

Recommendation: Rewrite the docstring to state that all agents use Opus 4.7 pricing, or restore Sonnet pricing for meta_prompter if that's the intended cost model. Keep the note about the 70/30 input/output assumption.

low Severity guide for findings is undocumented for users ~1.0h ▶

src/spectra/entities/enums.py:10-11

Severity (critical|high|medium|low|info) is defined as a Literal in entities/enums.py with a one-liner docstring 'Finding severity from most to least urgent', but there's no user-facing guide explaining what each level means in Spectra's report. Specialist prompts contain calibration internally, but the public docs (API.md, README) are unverified, and entity docs don't define the semantics for report consumers.

Recommendation: Either expand the Severity docstring with a per-level definition (critical = exploit/data loss; high = major bug; medium = code smell; low = style; info = note) or add a 'Severity Levels' section to API.md / README and link from the docstring.

low Public CLI cache subcommands lack a getting-started example ~2.0h ▶

src/spectra/adapters/cli_controller.py:312-396

The 'spectra cache' Typer subapp exposes stats/clear/prune with non-trivial flags (--older-than 30d|4w|1m, --include-hit-log, --dry-run, --json, --yes, optional repo URL or 32-hex signature). The functions have docstrings but there's no aggregated reference showing typical workflows (e.g., 'inspect cache size before pruning', 'CI: spectra cache prune --older-than 7d --dry-run'). Users will reverse-engineer behavior from --help.

Recommendation: Add a 'Cache management' section in docs/guides/getting-started.md (or a dedicated docs/guides/cache.md) with end-to-end examples for each subcommand and the JSON output schema (CacheStats fields).

low SPEC-010 error code not surfaced to users despite being raised ~2.0h ▶

src/spectra/entities/errors.py:30-50

ERRORS dict defines SPEC-010 'Cache I/O failed' (retryable=False), and main.py swallows it on cache init/close paths. The errors registry is internal but no user-facing doc enumerates all SPEC-* codes. When users see 'SPEC-002: Anthropic API unreachable' in CLI output, they have nowhere to look up code meanings or suggested actions.

Recommendation: Add a 'Troubleshooting / Error Codes' section to README.md or docs/guides/troubleshooting.md listing each SPEC-* code, what it means, whether it's retryable, and remediation tips. Keep the list in sync via a generated table from ERRORS dict if possible.

estimated effort: ~6h

Maintainability (3)

medium Runtime dependencies use lower-bound-only version specifiers ~1.0h ▶

pyproject.toml:27-33

All seven runtime dependencies in pyproject.toml use unbounded lower-bound specifiers (e.g. anthropic>=0.40, pydantic>=2.5, jinja2>=3.1). Without upper bounds, a future major release with breaking changes (e.g. pydantic 3.x, anthropic 1.x) will be silently installed and may break end-user installations. For a published package on PyPI (spectra-ai 0.3.3), this is a reproducibility and supply-chain stability risk. The Anthropic SDK in particular has had breaking changes between minor versions.

Recommendation: Add upper bounds to runtime dependencies, e.g. 'anthropic>=0.40,<1.0', 'pydantic>=2.5,<3', 'jinja2>=3.1,<4'. This caps the API surface to known-compatible major versions and is standard practice for PyPI-published libraries.

medium gitpython runtime dependency carries known historical CVE history ~0.5h ▶

pyproject.toml:31-31

gitpython>=3.1.30 is pinned with no upper bound. The 3.1.x line has had multiple security advisories (e.g. CVE-2023-40590 RCE on Windows in 3.1.32 and earlier, CVE-2023-41040 blind local file inclusion in 3.1.32 and earlier). The floor 3.1.30 is below the fixed versions for these CVEs. A fresh install on a system where pip resolves to 3.1.30 would pull a vulnerable version.

Recommendation: Raise the gitpython floor to a version past the known CVEs, e.g. 'gitpython>=3.1.41,<4'. Cross-check against GitHub's GHSA database for gitpython before finalizing.

low Dev dependency group lacks pip-audit / safety / bandit for self-scanning ~1.5h ▶

pyproject.toml:38-46

The [dev] optional-dependencies group contains test/lint/type tooling but no dedicated supply-chain scanner (pip-audit, safety, or osv-scanner). For a project whose business is finding security issues in other repos, the absence of automated CVE scanning of its own dependency tree in CI is a notable gap. Ruff's 'S' bandit rules cover code patterns but not transitive CVEs.

Recommendation: Add pip-audit (or osv-scanner) to the dev group and a CI job that runs it on every PR. Combine with Dependabot's security-updates for end-to-end CVE coverage.

estimated effort: ~3h

Performance (6)

medium Sequential file reads in heuristic source loader block pipeline startup ~1.5h ▶

src/spectra/infrastructure/main.py:245-260

_read_key_source_files iterates up to 20 files sequentially, awaiting git_port.read_file and tiktoken counting one at a time. Each read is async I/O but they're not concurrent, so wall-clock latency = sum of individual reads instead of max. On large repos with slow disk, this adds noticeable startup overhead before the parallel specialist stage can begin. asyncio.gather with a small semaphore would parallelize this safely.

Recommendation: Use asyncio.gather with a semaphore (e.g., 5-10 concurrent reads) to read files in parallel. Tokens can still be counted sequentially after gather since tiktoken is CPU-bound and fast. Alternatively, read all bytes first, then count tokens in a thread pool.

medium No concurrency bound on parallel specialist agent execution ~3.0h ▶

src/spectra/use_cases/orchestrate_agents.py

Specialists run via asyncio.gather over all 6 agents simultaneously. Each agent makes a long-running Anthropic API call with effort=xhigh and up to 80K output tokens. Without a semaphore or rate-limit-aware scheduler, all 6 hit the API at once and can trigger 429 rate limits, causing the RetryDecorator to back off all 6 in lockstep. This wastes wall-clock time vs. staggering or limiting concurrency to 3-4.

Recommendation: Add an asyncio.Semaphore (e.g., concurrency=4) around specialist invocations, or implement a token-bucket rate limiter aware of Anthropic's tier limits. Alternatively, use exponential jitter on the retry decorator (currently fixed 1s/2s/4s) to desynchronize retries.

medium Fixed exponential backoff without jitter causes thundering-herd retries ~1.0h ▶

src/spectra/infrastructure/retry_decorator.py

RetryDecorator uses backoff_base=1.0 with deterministic 1s/2s/4s delays (per docstring). When all 6 specialists hit a 429 rate limit simultaneously, they all retry at exactly t+1s, t+3s, t+7s, repeatedly hammering the API in synchronized waves. Adding jitter (random 0-1s offset) would spread retries and improve overall throughput under contention.

Recommendation: Introduce random jitter in backoff: sleep_time = backoff_base * (2 ** attempt) + random.uniform(0, backoff_base). For 429 responses, prefer the Retry-After header from Anthropic when present.

low _prioritize_source_files iterates file tree 4 times implicitly via tier classification ~1.0h ▶

src/spectra/infrastructure/main.py:268-285

The tier classification loop is O(n) but each path runs through 4 conditional checks plus a Path() construction. For a 50K-file tree this is ~200K Python-level operations on the main thread, blocking the event loop briefly during INGEST. Path objects are also allocated per file (50K allocations).

Recommendation: Avoid Path() allocation: use os.path.splitext / str.rsplit for stem and suffix extraction (5-10× faster). Short-circuit non-source extensions with a single suffix check before tier dispatch. For very large trees, consider running this in a thread via asyncio.to_thread.

low Composite prompt/model version recomputation per call to factory ~0.5h ▶

src/spectra/infrastructure/main.py:200-230

_make_cache_key_factory calls _composite_model_versions() and _composite_prompt_versions() once per analysis run, but _composite_prompt_versions iterates all SPECIALIST_CONFIGS and computes a blake2b digest over potentially hundreds of KB of prompt text. This is fine per-run but if cache_key_factory is invoked many times (e.g., per-batch in Phase 3), recomputation could become a hotspot. Currently mitigated since the factory closes over the precomputed values, but _bind_cache_run_context computes them again.

Recommendation: Memoize _composite_model_versions and _composite_prompt_versions at module scope using functools.cache — they are pure functions of constants. Compute once, share between cache binding and key factory.

low Token counting via tiktoken_adapter not reused across agents — same content counted multiple times ~2.0h ✓ validated ▶

src/spectra/infrastructure/main.py:240-260

Each specialist receives the same source_files dict and likely calls token-counting on the same content. If 6 specialists each tokenize the same 100K-token corpus, that's 6× redundant CPU work (~6×100ms = 0.6s blocking). The TiktokenAdapter docstring mentions hash-based caching, but if the cache is per-instance and a fresh adapter is created per agent, the cache is cold each time.

Recommendation: Use a module-level shared TiktokenAdapter singleton with content-hash → token-count LRU cache. Inject the same instance into all consumers (orchestrate_agents, manage_token_budget, _read_key_source_files). Pre-tokenize source_files once and pass token counts in the AgentContext rather than re-counting downstream.

estimated effort: ~9h

Cross-Cutting Insights

Patterns identified by CritiqueAgent that span multiple dimensions

arch-000, arch-004, arch-008, qual-005, qual-011 all describe the same root cause: model/prompt/role identifiers duplicated across multiple modules with no single source of truth. Fixing once (canonical constants module) addresses architecture, quality, and DRY concerns simultaneously.

doc-001, doc-002, doc-003 all stem from a model rename (Sonnet→Opus) that updated code but missed documentation strings. A single sweep of model references across docstrings/banners resolves all three.

arch-002, arch-007, qual-004 converge on main.py being overloaded with non-DI orchestration. Extracting Stage 1/Stage 6 into use cases solves all three.

arch-003 and qual-008 are duplicate findings about CLI module globals from architecture vs quality lenses — single fix (CliContext) addresses both.

arch-006 and qual-001 both describe the BaseAgent contract mismatch for non-finding agents — single refactor (parametric BaseAgent[T] or split ABCs) resolves both.

sec-002, sec-007, qual-002 share the pattern of bare except-and-swallow without scrubbing/logging; a unified error-handling policy with redaction and DEBUG logging addresses all three.

perf-002, perf-003 together describe synchronized rate-limit thundering herd; concurrency cap + jitter must ship together for either to be effective.

Several doc-* and dep-* findings (doc-004/005/007/008/009, dep-002/003) admit source material was not provided — these reflect audit scope gaps rather than code defects and should be reframed as 'audit completion items' not 'findings.'

Technical Debt Summary

0 estimated hours to remediate

cost to remediate: ~$10,894 at $150/hr avg dev rate

By Dimension

Architecture 22.8h

Security 11.0h

Quality 10.0h

Performance 9.0h

Documentation 6.5h

Maintainability 3.0h

By Severity

medium 33.0h

low 26.2h

info 3.0h

Debt Distribution

medi

low

Due Diligence Compliance Mapping

OWASP Top 10 (2021) Coverage

2 of 10 categories checked

A01:2021 Broken Access Control

A02:2021 Cryptographic Failures

A03:2021 Injection

A04:2021 Insecure Design

A05:2021 Security Misconfiguration

A06:2021 Vulnerable and Outdated Components

A07:2021 Identification and Auth Failures

A08:2021 Software and Data Integrity Failures

A09:2021 Security Logging and Monitoring Failures

A10:2021 Server-Side Request Forgery

OWASP Top 10 (2025) Coverage

2 of 10 categories checked

A01:2025 Broken Access Control

A02:2025 Security Misconfiguration

A03:2025 Software Supply Chain Failures

A04:2025 Cryptographic Failures

A05:2025 Injection

A06:2025 Insecure Design

A07:2025 Authentication Failures

A08:2025 Software or Data Integrity Failures

A09:2025 Logging and Alerting Failures

A10:2025 Mishandling of Exceptional Conditions

CWE References Found

CWE-20 CWE-22 CWE-79 CWE-117 CWE-209 CWE-367 CWE-459 CWE-532 CWE-755

AI-assisted screening based on finding text. Not a substitute for professional penetration testing.

Investment Readiness Score

⚠ Automated heuristic — not a substitute for formal due diligence or financial advisory. Score is derived from code-quality signals, not business fundamentals.

0 / 100

needs work

Moderate technical risk. Several areas need attention before fundraising.

Component Breakdown

Overall Score

85 25%

Security Posture

89 20%

Issue Concentration

48 10%

Dependency Health

10 10%

Code Complexity

50 10%

License Compliance

95 10%

SOC 2 Readiness

48 10%

Critical Findings

100 5%

AI-estimated composite score. Consult qualified advisors for investment decisions.

SOC 2 Readiness

⚠ Automated heuristic — not a substitute for formal SOC 2 assessment. Findings are mapped by keyword analysis, not control evidence evaluation.

48.5% control coverage

16 of 33 controls addressed
17 gaps · 26 findings mapped

CC1: Control Environment 1/5

✗ CC1.1 Integrity and ethical values

✗ CC1.2 Board independence and oversight

✓ CC1.3 Management structure and reporting 2

✗ CC1.4 Commitment to competence

✗ CC1.5 Accountability for internal controls

CC2: Communication and Information 2/3

✓ CC2.1 Information for internal control 2

✓ CC2.2 Internal communication of objectives 2

✗ CC2.3 External communication

CC3: Risk Assessment 3/4

✓ CC3.1 Specification of suitable objectives 4

✓ CC3.2 Risk identification and analysis 2

✓ CC3.3 Consideration of fraud risk 4

✗ CC3.4 Identification of significant changes

CC4: Monitoring Activities 1/2

✗ CC4.1 Ongoing and separate evaluations

✓ CC4.2 Communication of deficiencies 1

CC5: Control Activities 2/3

✓ CC5.1 Selection of control activities 2

✗ CC5.2 Technology general controls

✓ CC5.3 Deployment through policies 1

CC6: Logical and Physical Access Controls 3/8

✗ CC6.1 Logical access security software

✓ CC6.2 Credential and secret management 3

✓ CC6.3 Role-based access authorization 1

✗ CC6.4 Access removal and session management

✗ CC6.5 Physical access restrictions

✗ CC6.6 System boundary protection

✓ CC6.7 Data transmission security 1

✗ CC6.8 Prevention of unauthorized software

CC7: System Operations 2/5

✗ CC7.1 Infrastructure and availability monitoring

✗ CC7.2 Security event detection

✓ CC7.3 Security event evaluation 1

✓ CC7.4 Incident response procedures 1

✗ CC7.5 Recovery and resilience

CC8: Change Management 0/1

✗ CC8.1 Change control processes

CC9: Risk Mitigation 2/2

✓ CC9.1 Risk mitigation for business disruptions 1

✓ CC9.2 Third-party and vendor risk management 2

Keyword-based mapping to AICPA Common Criteria (CC1–CC9). Not a formal SOC 2 audit.

PCI DSS 4.0 — Requirement 6

⚠ Automated heuristic — not a substitute for formal PCI DSS assessment. Findings are mapped by keyword analysis, not control evidence evaluation.

36.4% control coverage

4 of 11 controls addressed
7 gaps · 7 findings mapped

R6.2: Secure Software Development 1/4

✗ 6.2.1 Secure development processes defined

✗ 6.2.2 Software development personnel trained

✗ 6.2.3 Code reviewed before release

✓ 6.2.4 Protection against common vulnerabilities 3

R6.3: Security Vulnerabilities Identified and Addressed 2/3

✓ 6.3.1 Known vulnerabilities identified 2

✓ 6.3.2 Software inventory maintained 3

✗ 6.3.3 Patches applied timely

R6.4: Public-Facing Web Applications Protected 0/2

✗ 6.4.1 Web application firewall or equivalent

✗ 6.4.2 Automated attack detection

R6.5: Changes Managed Securely 1/2

✓ 6.5.1 Change control procedures 1

✗ 6.5.2 Development/test/production separation

Keyword-based mapping to PCI DSS 4.0 Requirement 6 (Secure Systems & Software). Not a formal PCI assessment.

NIST CSF 2.0

⚠ Automated heuristic — not a substitute for formal NIST CSF assessment. Findings are mapped by keyword analysis, not control evidence evaluation.

58.3% function coverage

7 of 12 categories addressed
5 gaps · 14 findings mapped

GV: Govern 1/2

✓ GV.OC-01 Organizational context understood 1

✗ GV.RM-01 Risk management objectives established

ID: Identify 2/2

✓ ID.AM-01 Asset inventory maintained 6

✓ ID.RA-01 Risk assessment performed 2

PR: Protect 1/3

✗ PR.AA-01 Access control enforced

✓ PR.DS-01 Data security ensured 3

✗ PR.PS-01 Platform security maintained

DE: Detect 1/2

✓ DE.CM-01 Continuous monitoring implemented 2

✗ DE.AE-01 Adverse event analysis performed

RS: Respond 1/2

✓ RS.AN-01 Incident analysis conducted 1

✗ RS.MI-01 Incident mitigation applied

RC: Recover 1/1

✓ RC.RP-01 Recovery execution planned and tested 1

Keyword-based mapping to NIST Cybersecurity Framework 2.0 (6 Functions). Not a formal NIST assessment.

Issue Concentration

distribution score

concerning

0.523

Gini Coefficient

Unique Files

Total Issues

Top 10 Hotspot Files

1 15

src/spectra/infrastructure/main.py
2 7

src/spectra/adapters/cli_controller.py
3 3

pyproject.toml
4 2

src/spectra/infrastructure/agents/specialist_agent.py
5 2

src/spectra/entities/models.py
6 1

src/spectra/infrastructure/agents/agent_factory.py
7 1

src/spectra/infrastructure/agents/base_agent.py
8 1

src/spectra/infrastructure/agents/critique_agent.py
9 1

src/spectra/infrastructure/agents/specialist_prompts.py
10 1

src/spectra/infrastructure/agents/meta_prompter.py

Measures finding distribution across files. For contributor-based bus factor analysis, use git blame tools.

Dependency Risk

0 risk

critical risk

3 dependency findings analyzed · +10 severity penalty

Risk Signals Detected

vulnerable +25 pts
cve +20 pts
pinned +5 pts
cve +20 pts
transitive +10 pts

License Compliance

3 unique licenses detected · 14 total mentions

MIT×11 ISC×2 PROPRIETARY×1

Code Complexity

1 file flagged for complexity by specialists. No numeric complexity scores were extracted from finding text.

Files flagged for complexity by specialists

medium _run_analysis function exceeds 100 lines and has 7 boolean/string parameters src/spectra/infrastructure/main.py

ROI Analysis

This analysis cost

$5.09

Manual equivalent ($175/hr × 6h)

$1015

Spectra saved you

$1010 (99%)

Cost per finding

$0.13

Based on $175/hr senior engineer rate and ~6 hours for equivalent manual review. Actual costs vary.